uv — Projects & Dependencies¶

uv init my-api              # new directory
uv init                     # current directory
uv init --lib my-lib        # library (src/ layout)
uv init --app my-app        # application (flat layout)

[project]
name = "my-api"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = ["fastapi>=0.115", "httpx>=0.28"]

[dependency-groups]
dev = ["ruff>=0.11", "mypy>=1.15", "pytest>=8.3"]
test = ["pytest-cov>=6.1"]

uv add httpx                      # runtime dep
uv add "httpx>=0.28,<1.0"        # with constraint
uv add --dev ruff mypy            # dev group
uv add --group test pytest-cov    # named group
uv add git+https://github.com/org/repo@v2.0   # git
uv add ./libs/my-lib              # local path

uv remove httpx
uv remove --dev ruff

uv lock                          # resolve → uv.lock
uv lock --upgrade                # upgrade all
uv lock --upgrade-package httpx  # upgrade one

uv sync                          # install from lockfile
uv sync --locked                 # CI strict: fail if lockfile is outdated
uv sync --frozen                 # use lockfile as-is (skip freshness check)
uv sync --no-dev                 # production only
uv sync --all-groups             # all groups

uv tree                          # dependency tree
uv tree --invert --package httpx # who depends on httpx?
uv export --format requirements.txt --no-dev  # → requirements.txt

# pyproject.toml
[[tool.uv.index]]
name = "internal"
url = "https://pypi.company.example/simple"

uv add --index internal my-private-package
uv auth login https://pypi.company.example/simple