uv-python-projects

UV Python Projects

Implement modern Python project management using UV for 10-100x faster dependency resolution, comprehensive tooling, and streamlined development workflows.

Core Principles

• Use UV as the single tool for Python project lifecycle management
• Maintain reproducible environments with lockfiles and version pinning
• Leverage UV's global cache for optimal performance and disk efficiency
• Follow modern Python packaging standards with pyproject.toml
• Implement security-first dependency management practices

Project Initialization

New Project Setup

# Initialize new project with UV
uv init my-project
cd my-project

# Or initialize in existing directory
uv init .

# Initialize with specific Python version
uv init --python 3.12 my-project

Modern Project Structure

my-project/
├── src/
│   └── my_project/
│       ├── __init__.py
│       └── main.py
├── tests/
│   └── test_main.py
├── pyproject.toml      # Project configuration
├── uv.lock            # Lockfile (commit to version control)
├── .python-version     # Python version pinning
├── README.md
└── .gitignore

Essential pyproject.toml Template

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

[project]
name = "my-project"
version = "0.1.0"
description = "A modern Python project using UV"
readme = "README.md"
requires-python = ">=3.10"
authors = [
    { name = "Your Name", email = "[email protected]" }
]
classifiers = [
    "Development Status :: 4 - Beta",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
]
dependencies = [
    # Production dependencies go here
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0",
    "black>=23.0",
    "ruff>=0.1",
    "mypy>=1.0",
]
test = [
    "pytest>=7.0",
    "pytest-cov>=4.0",
]
docs = [
    "mkdocs>=1.5",
    "mkdocs-material>=9.0",
]

[project.scripts]
my-project = "my_project.main:main"

[tool.ruff]
target-version = "py310"
line-length = 88
select = ["E", "F", "I", "N", "W", "UP"]

[tool.black]
target-version = ["py310"]
line-length = 88

[tool.mypy]
python_version = "3.10"
strict = true

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-ra -q --strict-markers"
markers = [
    "slow: marks tests as slow",
    "integration: marks tests as integration tests",
]