Day 3 — UV Workflow#

Goal: Learn the day-to-day uv commands to create projects, manage dependencies, run scripts, and keep your Python environment reproducible.

What Is UV?#

uv is an extremely fast Python package and project manager built by Astral (the same team behind ruff). It replaces several tools:

Why uv? It’s 10-100x faster than pip. A full dependency install that takes pip 30 seconds takes uv under 1 second.

Installing UV#

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

# Verify:
uv --version

If uv is not found after install, add it to your PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Managing Python Versions#

# See what Python versions are available:
uv python list

# Install a specific version:
uv python install 3.13

# See installed versions:
uv python list --only-installed

Creating a New Project#

Method 1: Application (script/app you run)#

uv init my-app
cd my-app

This creates:

my-app/
├── .python-version     ← which Python version to use
├── README.md
├── main.py             ← entry point
└── pyproject.toml      ← project metadata + dependencies

Method 2: Library (package others install)#

uv init --lib my-library
cd my-library

This creates:

my-library/
├── .python-version
├── README.md
├── pyproject.toml
└── src/
    └── my_library/
        ├── __init__.py
        └── py.typed

The --lib flag creates a src/ layout — best practice for publishable packages.

🧠 Knowledge Check#

Q1: If you are building a tool that you intend to publish as a reusable Python package, which command should you use to initialize it?

• A) uv init my-library
• B) uv init --lib my-library
• C) uv create my-library
• D) uv new my-library

Managing Dependencies#

Adding packages#

# Add a dependency:
uv add requests
uv add pandas numpy

# Add a development-only dependency:
uv add --dev pytest ruff

# Add with version constraints:
uv add "requests>=2.31"
uv add "pandas>=2.0,<3.0"

What happens when you uv add:#

1. Installs the package into .venv/
2. Adds it to pyproject.toml under [project.dependencies]
3. Updates uv.lock with exact resolved versions

Removing packages#

uv remove requests

Syncing (installing from lockfile)#

# Install everything from uv.lock:
uv sync

# Install including dev dependencies:
uv sync --all-groups

When to use uv sync: After cloning a repo, or after pulling changes that updated pyproject.toml or uv.lock.

Running Scripts and Commands#

uv run — Run inside the project environment#

# Run a Python script:
uv run python main.py

# Run a module:
uv run python -m pytest

# Run any command in the project's environment:
uv run ruff check .

uv run automatically:

• Creates the .venv/ if it doesn’t exist
• Syncs dependencies if needed
• Runs the command inside the environment

uvx — Run CLI tools without installing#

# Run a tool without adding it to your project:
uvx ruff check .
uvx black main.py
uvx httpie GET https://httpbin.org/get

uvx is like npx for Python — runs a tool in a temporary, isolated environment.

The pyproject.toml File#

This is the heart of your project. Here’s what a typical one looks like:

[project]
name = "my-app"
version = "0.1.0"
description = "A cool tool built during TDS bootcamp"
readme = "README.md"
requires-python = ">=3.11"
dependencies = [
    "httpx>=0.27",
    "rich>=13.0",
]

[dependency-groups]
dev = [
    "pytest>=8",
    "ruff>=0.8",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

🧠 Knowledge Check#

Q1: Which file does uv use to keep track of project metadata and required dependencies?

• A) requirements.txt
• B) package.json
• C) pyproject.toml
• D) Pipfile

The uv.lock File#

The lockfile pins exact versions of every dependency (including transitive ones):

# This file is auto-generated by uv
# Do not edit manually

[[package]]
name = "httpx"
version = "0.27.2"
source = { registry = "https://pypi.org/simple" }
dependencies = [
    { name = "anyio" },
    { name = "certifi" },
    ...
]

Why it matters:

• pyproject.toml says “I need httpx >= 0.27”
• uv.lock says “I need httpx == 0.27.2 with anyio == 4.6.2 with certifi == 2024.8.30 …”

The lockfile ensures everyone gets exactly the same versions.

Commit both pyproject.toml AND uv.lock to Git.

Complete Workflow Example#

Let’s build a tiny tool from scratch:

# 1. Create project
uv init weather-report
cd weather-report

# 2. Add dependencies
uv add httpx rich

# 3. Write the code
cat > main.py << 'PYEOF'
"""Fetch and display weather data."""
import httpx
from rich.console import Console
from rich.table import Table

console = Console()

def get_weather():
    """Fetch weather data from a public API."""
    url = "https://wttr.in/?format=j1"
    response = httpx.get(url, timeout=10)
    data = response.json()

    current = data["current_condition"][0]

    table = Table(title="Current Weather")
    table.add_column("Metric", style="cyan")
    table.add_column("Value", style="green")

    table.add_row("Temperature", f"{current['temp_C']}°C")
    table.add_row("Feels Like", f"{current['FeelsLikeC']}°C")
    table.add_row("Humidity", f"{current['humidity']}%")
    table.add_row("Description", current["weatherDesc"][0]["value"])

    console.print(table)

if __name__ == "__main__":
    get_weather()
PYEOF

# 4. Run it
uv run python main.py

# 5. Add a test
uv add --dev pytest

cat > test_main.py << 'PYEOF'
from main import get_weather

def test_get_weather_runs():
    """Smoke test — just make sure it doesn't crash."""
    # This will make a real HTTP call
    get_weather()
PYEOF

# 6. Run tests
uv run pytest -v

# 7. Check what's in the project
tree -a -I '.git|.venv|__pycache__'

UV Command Cheatsheet#

Q&A#

uv add --upgrade requests    # update a specific package
uv lock --upgrade            # update all packages to latest compatible versions
uv sync                      # install the updated versions

git clone <repo-url>
cd <repo>
uv sync         # installs exact versions from uv.lock
uv run python main.py

Exercises#

Exercise 1: Create and run a project

uv init /tmp/uv-practice
cd /tmp/uv-practice
uv add rich

Write a script that prints a styled message:

# main.py
from rich import print
print("[bold magenta]Hello from UV![/bold magenta]")
print("[green]Dependencies are managed automatically.[/green]")

uv run python main.py

Exercise 2: Inspect the project structure

cat pyproject.toml
ls -la .venv/bin/ | head -10
cat .python-version

Exercise 3: Add and remove packages

uv add httpx
cat pyproject.toml   # httpx should appear in dependencies

uv remove httpx
cat pyproject.toml   # httpx should be gone

Exercise 4: MCQ

Q1: What does uv init --lib my-package create that uv init my-app does not?

• A) A pyproject.toml file
• B) A src/ directory with proper package layout
• C) A virtual environment
• D) A README.md file

Q2: After cloning a uv project, which single command sets up the environment?

• A) pip install -r requirements.txt
• B) uv sync
• C) python3 -m venv .venv
• D) uv init

Clean up:

rm -rf /tmp/uv-practice