uv - The Python Package Manager You've Been Waiting For

# To start a "simple" project, you needed:
pip install pipx          # to safely install global tools
pipx install poetry       # to manage dependencies
poetry self add poetry-plugin-shell  # to activate the venv via poetry
poetry python install 3.12           # to install the Python version
poetry new my-project     # to create the project
poetry shell              # to activate the environment
poetry add fastapi        # finally, install what you actually wanted

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

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Via pip
pip install uv

# Via Homebrew (macOS)
brew install uv

source ~/.bashrc   # or ~/.zshrc

uv --version
# uv 0.5.x (...)

[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "fastapi[standard]>=0.115.0",
]

[dependency-groups]
dev = [
    "pytest>=8.0.0",
    "ruff>=0.9.0",
]

# Option 1: create the folder and initialize
uv init my-project
cd my-project

# Option 2: initialize in the current folder
mkdir my-project && cd my-project
uv init

# List available versions
uv python list

# Install a version
uv python install 3.13

# Pin the version for this project (creates/updates .python-version)
uv python pin 3.13

# Main dependency
uv add fastapi

# With extras (equivalent to pip install fastapi[standard])
uv add "fastapi[standard]"

# Development dependency
uv add --dev pytest ruff

# Specific version range
uv add "sqlalchemy>=2.0,<3.0"

# Sync the environment with pyproject.toml / uv.lock
uv sync

# Without dev dependencies (useful in production)
uv sync --no-dev

uv remove fastapi

# Run the application
uv run fastapi dev my_project/app.py

# Run tests
uv run pytest

# Run a script
uv run python script.py

# Open the interactive interpreter
uv run python

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

# 1. Create the project
uv init fast-zero
cd fast-zero

# 2. Create the Python package
mkdir fast_zero
touch fast_zero/__init__.py

# 3. Install dependencies
uv add "fastapi[standard]"
uv add --dev pytest pytest-cov ruff taskipy

# 4. Run (after creating app.py as shown below)
uv run fastapi dev fast_zero/app.py

from fastapi import FastAPI

app = FastAPI()


@app.get('/')
def read_root():
    return {'message': 'Hello, World!'}

# ─────────────────────────────────────────────
# [project] — metadata and main dependencies
# Essential project information and packages
# required to run in production.
# ─────────────────────────────────────────────
[project]
name = "fast-zero"          # project name (kebab-case by convention)
version = "0.1.0"           # current project version
requires-python = ">=3.12"  # minimum accepted Python version
dependencies = [
    # fastapi with the [standard] group, which includes uvicorn, httpx
    # and other useful extras for development and production
    "fastapi[standard]>=0.115.0",
]

# ─────────────────────────────────────────────
# [dependency-groups] — development dependencies
# Packages used only during development
# (tests, linting, formatting). Not included in production.
# ─────────────────────────────────────────────
[dependency-groups]
dev = [
    "pytest>=8.0.0",      # testing framework
    "pytest-cov>=6.0.0",  # plugin to measure test coverage
    "ruff>=0.9.0",        # linter and code formatter
    "taskipy>=1.14.0",    # task runner — shortcuts for project commands
]

# ─────────────────────────────────────────────
# [tool.ruff] — global Ruff configuration
# Defines behaviors that apply to both
# the linter and the formatter.
# ─────────────────────────────────────────────
[tool.ruff]
line-length = 79             # maximum characters per line (PEP 8 standard)
extend-exclude = ['migrations']  # ignores the migrations folder (auto-generated
                                 # code — we don't want ruff to touch it)

# ─────────────────────────────────────────────
# [tool.ruff.lint] — linter configuration
# Defines which best-practice rules ruff
# will check in the code.
# ─────────────────────────────────────────────
[tool.ruff.lint]
preview = true  # enables rules still in experimental phase
select = [
    'I',   # isort — checks alphabetical ordering of imports
    'F',   # pyflakes — detects common errors (unused variables, unnecessary imports)
    'E',   # pycodestyle errors — code style errors
    'W',   # pycodestyle warnings — code style warnings
    'PL',  # pylint — general Python best practices
    'PT',  # flake8-pytest — best practices specific to pytest tests
]

# ─────────────────────────────────────────────
# [tool.ruff.format] — formatter configuration
# Defines the automatic code formatting style.
# ─────────────────────────────────────────────
[tool.ruff.format]
preview = true          # enables experimental formatting behaviors
quote-style = 'single'  # uses single quotes instead of double (team preference)

# ─────────────────────────────────────────────
# [tool.pytest.ini_options] — pytest configuration
# Defines how pytest behaves when running tests.
# ─────────────────────────────────────────────
[tool.pytest.ini_options]
pythonpath = "."           # adds the project root to PYTHONPATH, enabling
                           # imports like "from fast_zero.app import app"
addopts = '-p no:warnings' # suppresses warnings from external libraries to
                           # keep test output clean

# ─────────────────────────────────────────────
# [tool.taskipy.tasks] — command shortcuts
# Defines tasks runnable with "uv run task <name>".
# Saves you from memorizing long flags and paths.
# ─────────────────────────────────────────────
[tool.taskipy.tasks]
lint   = 'ruff check'                        # checks best practices in the code
format = 'ruff format'                       # formats the code automatically
run    = 'fastapi dev fast_zero/app.py'      # starts the development server
test   = 'pytest -s -x --cov=fast_zero -vv' # runs tests with:
                                             #   -s: shows prints during tests
                                             #   -x: stops on first failure
                                             #   --cov=fast_zero: measures package coverage
                                             #   -vv: verbose output

uv run task test
uv run task lint
uv run task run

# Install a tool globally
uv tool install ruff
uv tool install httpie
uv tool install black

# Run without installing (temporary environment, equivalent to pipx run)
uvx ruff check .
uvx black --check .

# List installed tools
uv tool list

# Upgrade
uv tool upgrade ruff

# Remove
uv tool uninstall black

# script.py
# /// script
# requires-python = ">=3.12"
# dependencies = [
#   "httpx",
#   "rich",
# ]
# ///

import httpx
from rich import print

response = httpx.get("https://api.github.com/repos/astral-sh/uv")
print(response.json()["stargazers_count"])

uv run script.py
# Automatically installs deps in an isolated env and runs the script

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

# 2. In your project directory, sync
# uv can read Poetry's pyproject.toml natively
uv sync

# 3. Swap your day-to-day commands
# poetry run pytest   →   uv run pytest
# poetry add X        →   uv add X
# poetry shell        →   source .venv/bin/activate  (or just use uv run)

# 4. (Optional) Generate uv.lock and remove poetry.lock
uv lock
git rm poetry.lock
git add uv.lock

DATABASE_URL=postgresql://localhost/dev uv run python manage.py migrate

# uv doesn't read .env automatically — use python-dotenv or direnv
uv add --dev python-dotenv

uv pip list
uv pip show fastapi

uv lock --upgrade
uv sync

uv pip compile pyproject.toml -o requirements.txt
# or, for production only:
uv export --no-dev -o requirements.txt

uv run --with fastapi --with uvicorn python -c "
import uvicorn
from fastapi import FastAPI
app = FastAPI()

@app.get('/')
def root(): return {'ok': True}

uvicorn.run(app)
"

name: Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v4
        with:
          version: "latest"

      - name: Install dependencies
        run: uv sync --frozen

      - name: Run tests
        run: uv run pytest

FROM python:3.13-slim

# Install uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

WORKDIR /app

# Copy lockfile and install dependencies (cacheable layer)
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev

# Copy code
COPY . .

CMD ["uv", "run", "fastapi", "run", "fast_zero/app.py", "--port", "8000"]