Modern Python Development Environment with pyenv, Poetry, uv, and pyproject.toml

uv is now the recommended single tool for managing Python versions, virtual environments, and packages. Install it once, globally:

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

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

After installation, uv handles everything - you don't need pyenv, pip, or venv separately.

Use uv to install and pin a Python version per project. This creates a .python-version file that is committed to git - every developer on the team uses the same version automatically:

# Install a specific Python version
uv python install 3.14.0

# Pin it for this project (creates .python-version)
uv python pin 3.14.0

# Verify
uv python list

If you still prefer pyenv for version management, uv respects .python-version files from pyenv smoothly.

uv init creates a pyproject.toml and uv.lock file. uv sync creates the virtual environment and installs all dependencies from the lockfile in one command:

# New project
uv init myapp
cd myapp

# Or sync an existing repo after cloning
uv sync

The virtualenv is created at .venv/ automatically. You never need to activate it manually when using uv run.

Always add dependencies through uv add - this updates both pyproject.toml and uv.lock atomically, ensuring the lockfile stays consistent:

# Add a runtime dependency
uv add fastapi uvicorn[standard]

# Add a dev-only dependency
uv add --dev pytest ruff ty

# Remove a package
uv remove httpx

Never run pip install directly in a uv-managed project - it bypasses the lock file.

uv run executes commands in the project's virtualenv without activating it. This is the standard way to run scripts, tests, and tools:

# Run your app
uv run python main.py

# Run tests
uv run pytest -v

# Run the linter
uv run ruff check .

# Run the type checker
uv run ty check

# Run a one-off script (auto-installs dependencies from inline script metadata)
uv run scripts/migrate.py

This pattern works identically in CI/CD without any activation step.

Enforce formatting and linting on every commit with pre-commit. Ruff handles both formatting (replacing Black) and linting (replacing flake8 + isort) in a single fast pass:

uv add --dev pre-commit

Create .pre-commit-config.yaml:

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.9.0
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

Install the hooks:

uv run pre-commit install

Now every git commit automatically runs Ruff format + lint with auto-fix.