Mastering Python Development with UV: Write, Manage, and Run Code Like a Pro

UV, the Rust-powered Python package and project manager, is revolutionizing how developers build and manage Python applications. Built by Astral (creators of Ruff), UV combines blistering speed with modern workflows, making it ideal for beginners and experts alike. In this guide, you’ll learn how to write Python programs and run them successfully using UV’s powerful features. Let’s dive in!

Why UV? A Quick Primer

• Speed: UV is 8–115x faster than pip and pip-tools, thanks to Rust’s performance optimizations and advanced caching.
• Unified Toolchain: Replaces pip, virtualenv, poetry, and more with a single binary.
• Cross-Platform: Works seamlessly on macOS, Linux, and Windows.
• Beginner-Friendly: Familiar pip-like commands with zero learning curve.

Step 1: Install UV

UV can be installed via standalone scripts, pipx, or package managers like Homebrew:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
irm https://astral.sh/uv/install.ps1 | iex

# Verify installation
uv --version

Step 2: Create a Python Project

Initialize a Project

uv init my_project && cd my_project

This generates a project structure with essential files like app.py, requirements.txt, and a .gitignore.

Set Up a Virtual Environment

uv venv .venv  # Instantly creates a virtual environment

# Activate the environment
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows

UV’s virtual environments are 80x faster than Python’s native venv and fully compatible with existing tools.

Step 3: Install Dependencies

Install packages using UV’s pip-compatible interface:

uv pip install flask pandas  # Install Flask and Pandas
uv pip freeze > requirements.txt  # Lock dependencies

Need a specific version? Use constraints:

uv pip install "flask>=2.0.0"

Sync Dependencies

Share your project? Let others replicate your environment:

uv pip sync requirements.txt  # Installs exact versions from the lockfile

Step 4: Write and Run a Python Program

Example: Build a Flask API

Create app.py:

from flask import Flask

app = Flask(__name__)

@app.route('/')
def hello():
    return {"message": "Hello from UV!"}, 200

if __name__ == '__main__':
    app.run(debug=True)

Run the Application

UV simplifies execution with automatic dependency management:

uv run app.py

This command:

1. Activates the virtual environment.
2. Installs missing dependencies (if any).
3. Runs the script in an isolated environment.

Open http://localhost:5000 to see your API in action! 🚀

Advanced Features for Power Users

1. Cross-Platform Lockfiles

Generate reproducible environments with uv pip compile:

uv pip compile requirements.in -o requirements.txt

UV’s lockfiles work across macOS, Linux, and Windows, ensuring consistency in team workflows.

2. Script Execution with Inline Dependencies

Use PEP 723 annotations to declare dependencies directly in scripts:

# /// script.py
# dependencies = ["requests"]
import requests

response = requests.get("https://api.github.com")
print(response.json())

Run it with:

uv run script.py  # Installs `requests` automatically!

3. Manage Python Versions

Install and switch Python versions without pyenv:

uv python install 3.12  # Install Python 3.12
uv venv --python 3.12   # Create an environment with this version

4. Workspace Support

Manage multi-package projects (e.g., a FastAPI app + shared libraries) with Cargo-style workspaces:

# pyproject.toml
[tool.uv.workspace]
members = ["libraries/*"]

Run commands in specific workspace packages:

uv run --package my_library

Troubleshooting Common Issues

• Missing Dependencies: Use uv pip install --missing to auto-install missing packages.
• Version Conflicts: Leverage uv pip compile --upgrade to refresh resolutions.
• Platform-Specific Lockfiles: UV generates platform-specific requirements.txt by default. For cross-platform projects, use uv pip compile --platform-independent.

Why UV is a Game-Changer

• Speed: Rebuild environments in seconds, not minutes.
• Simplicity: One tool replaces a dozen.
• Future-Proof: Backed by Astral’s track record (Ruff has 16M+ monthly downloads) and a roadmap focused on Python’s evolving needs.

Get Started Today!

UV isn’t just a tool—it’s a paradigm shift. Whether you’re writing a simple script or managing a complex project, UV’s speed and simplicity will transform your workflow. Install it now and experience Python development at lightning speed ⚡.

curl -LsSf https://astral.sh/uv/install.sh | sh

Happy coding! 🐍✨