Python UV Project Management

Provides workflows and best practices for managing Python projects using uv — Astral's fast Python package and project manager.

Project Initialization

Create a new project with uv init:

# Named project in new directory
uv init my-project
cd my-project

# Initialize in current directory
uv init

Generated structure:

my-project/
├── .gitignore
├── .python-version
├── README.md
├── main.py
└── pyproject.toml

After the first uv run, uv sync, or uv lock, uv creates:

my-project/
├── .venv/
├── .python-version
├── README.md
├── main.py
├── pyproject.toml
└── uv.lock

Run the project immediately after init:

uv run main.py

uv auto-creates and syncs the virtual environment on every uv run invocation.

Core File Roles

File	Purpose	Commit?
pyproject.toml	Broad requirements, project metadata	Yes
uv.lock	Exact resolved versions, cross-platform	Yes
.python-version	Default Python version for the project	Yes
.venv/	Isolated virtual environment	No

Critical rule: Commit uv.lock to version control. It guarantees reproducible installs across machines and CI environments. Never edit it manually.

Managing Dependencies

Runtime Dependencies

# Add with automatic version constraint
uv add requests

# Add with explicit version constraint
uv add 'requests>=2.31.0'

# Add with extras
uv add 'pandas[excel,plot]'

# Add platform-specific dependency
uv add "jax; sys_platform == 'linux'"

Development Dependencies

Separate dev dependencies from published requirements using dependency groups:

# Add to the default dev group (not published to PyPI)
uv add --dev pytest ruff mypy

# Add to named groups for fine-grained control
uv add --group lint ruff
uv add --group test pytest pytest-cov
uv add --group docs mkdocs

Resulting pyproject.toml:

[dependency-groups]
dev = ["pytest>=8.1.1,<9"]
lint = ["ruff>=0.4.0"]
test = ["pytest", "pytest-cov"]

Groups can nest to avoid duplication:

[dependency-groups]
lint = ["ruff"]
test = ["pytest"]
dev = [
  {include-group = "lint"},
  {include-group = "test"},
]

Removing and Upgrading

# Remove a dependency
uv remove requests

# Upgrade a specific package to latest compatible version
uv lock --upgrade-package requests

# Upgrade all packages
uv lock --upgrade

Running Commands

Always use uv run — it ensures the environment is synced before execution:

# Run a Python script
uv run main.py

# Run a tool from the environment
uv add flask
uv run -- flask run -p 3000

# Run with a one-off extra dependency (not added to project)
uv run --with rich python -c "import rich; rich.print('[bold]Hello[/bold]')"

# Run only specific dependency groups
uv run --no-default-groups --group test pytest

Alternatively, sync and activate manually when needed (e.g., interactive shells):

# macOS/Linux
uv sync
source .venv/bin/activate

# Windows
uv sync
.venv\Scripts\activate

Do not use uv pip install for project dependencies — use uv add instead. Direct pip manipulation bypasses the lockfile and breaks reproducibility.

Dependency Sources

Override where packages are fetched from during development using tool.uv.sources:

# From a local path (editable)
uv add --editable ../my-lib

# From a Git repository
uv add git+https://github.com/encode/httpx

# Pin to a specific Git tag
uv add git+https://github.com/encode/httpx --tag 0.27.0

# From a custom index
uv add torch --index pytorch=https://download.pytorch.org/whl/cpu

Sources are a uv-only development feature. Use --no-sources to validate that published metadata is self-contained:

uv lock --no-sources
uv build --no-sources

Syncing and Locking

# Sync environment to lockfile (installs missing, removes extra)
uv sync

# Sync including all dependency groups
uv sync --all-groups

# Sync only specific groups
uv sync --group test

# Regenerate lockfile without syncing
uv lock

# Check if lockfile is up-to-date (for CI)
uv lock --check

Building and Viewing Version

# Build source distribution and wheel
uv build

# Check built artifacts
ls dist/
# my-project-0.1.0-py3-none-any.whl
# my-project-0.1.0.tar.gz

# View current package version
uv version
uv version --short        # 0.1.0 only
uv version --output-format json

Best Practices

Lockfile hygiene

• Commit uv.lock; never edit it manually
• Run uv lock --check in CI to detect uncommitted lockfile drift
• Use uv lock --upgrade-package <name> for targeted upgrades, not --upgrade carelessly

Dependency discipline

• Use --dev / --group for all non-runtime dependencies (linters, formatters, test runners, type checkers)
• Never use uv pip install directly in a project — always uv add
• Set requires-python in pyproject.toml to lock down supported versions

Environment hygiene

• Never commit .venv/; the generated .gitignore excludes it by default
• Use uv run rather than activating the venv manually in scripts and CI
• For one-off tools, prefer uvx <tool> over installing into the project environment

Publishing safety

• Run uv build --no-sources before publishing to validate published metadata is correct without tool.uv.sources overrides

pyproject.toml example (library pattern):

[project]
name = "my-lib"
version = "0.1.0"
description = "A short description"
readme = "README.md"
requires-python = ">=3.11"
dependencies = [
    "httpx>=0.27.0",
]

[project.optional-dependencies]
network = ["aiohttp>=3.9"]

[dependency-groups]
dev = [
    {include-group = "lint"},
    {include-group = "test"},
]
lint = ["ruff>=0.4.0", "mypy>=1.10"]
test = ["pytest>=8.0", "pytest-cov>=5.0"]

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

Quick Reference

Task	Command
Create project	uv init <name>
Run script	uv run <file.py>
Add dependency	uv add <package>
Add dev dependency	uv add --dev <package>
Add to named group	uv add --group <group> <package>
Remove dependency	uv remove <package>
Upgrade package	uv lock --upgrade-package <name>
Sync environment	uv sync
Rebuild lockfile	uv lock
Build distributions	uv build
Check version	uv version
Run tool one-off	uv run --with <pkg> python ...
Simulate no sources	uv lock --no-sources

Additional Resources

Reference Files

For detailed information, consult:

• references/dependency-management.md — Advanced dependency configuration: optional extras, platform markers, multiple sources, editable installs, and dependency specifier syntax
• references/project-structure.md — Deep dive on pyproject.toml, uv.lock, .python-version, workspace layout, and configuration options