Python UV Boilerplate

A modern, minimal Python project boilerplate using uv for fast, reliable dependency management.

Features

• Fast Dependency Management: Uses uv - an extremely fast Python package installer and resolver
• Modern Python: Python 3.10+ with type hints support
• Code Quality Tools:
  • Ruff - Lightning-fast Python linter and formatter
  • Pyright - Static type checker
  • pre-commit - Git hooks for code quality
• Testing: pytest with coverage support
• Makefile: Simple commands for common tasks

Prerequisites

• Python 3.10 or higher
• uv installed

Installing uv

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

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Alternative: Using pip
pip install uv

Quick Start

1. Clone or use this template:

   git clone <your-repo-url>
   cd python-uv-boilerplate

2. Install dependencies:

   make install
   # or manually:
   uv sync --all-groups
   uv run pre-commit install

3. Run the application:

   make run
   # or:
   uv run python main.py

Project Structure

.
├── main.py                 # Main application entry point
├── tests/                  # Test directory
├── pyproject.toml         # Project dependencies and configuration
├── uv.lock                # Locked dependencies
├── Makefile               # Common development tasks
├── .pre-commit-config.yaml # Pre-commit hooks configuration
└── README.md              # This file

Available Commands

Run make help to see all available commands:

make help               # Show all available commands
make install            # Install dependencies and setup pre-commit hooks
make sync               # Sync dependencies
make update             # Update dependencies
make clean              # Clean build artifacts and caches
make lint               # Run linter (ruff)
make lint-fix           # Run linter with auto-fix
make format             # Format code with ruff
make format-check       # Check code formatting
make type-check         # Run type checker (pyright)
make test               # Run tests
make test-cov           # Run tests with coverage report
make ci                 # Run all CI checks
make run                # Run main application

Development Workflow

Adding Dependencies

# Add a runtime dependency
uv add <package-name>

# Add a development dependency
uv add --group dev <package-name>

# Add to a specific group
uv add --group test pytest-mock

Running Tests

# Run all tests
make test

# Run tests with coverage
make test-cov

# Run specific test file
uv run pytest tests/test_example.py

Code Quality

# Format code
make format

# Check formatting
make format-check

# Run linter
make lint

# Fix linting issues automatically
make lint-fix

# Run type checker
make type-check

# Run all CI checks
make ci

Pre-commit Hooks

Pre-commit hooks automatically run on every commit to ensure code quality:

# Run pre-commit on all files
uv run pre-commit run --all-files

# Skip pre-commit hooks (not recommended)
git commit --no-verify

Configuration

Dependencies

Dependencies are managed in pyproject.toml:

• dependencies: Runtime dependencies
• dev: All development dependencies (includes lint, test, type-check groups)
• lint: Linting and formatting tools
• test: Testing tools
• type-check: Type checking tools

Code Style

• Line length: 120 characters
• Python version: 3.10+
• Linter: Ruff with common sense defaults
• Formatter: Ruff
• Type checker: Pyright in basic mode

Customization

1. Update project metadata in pyproject.toml:

   [project]
   name = "your-project-name"
   version = "0.1.0"
   description = "Your project description"

2. Add your code in main.py or create new modules

3. Add tests in the tests/ directory

4. Adjust configuration in pyproject.toml as needed

Why uv?

uv is a modern Python package installer and resolver that is:

• 10-100x faster than pip
• Drop-in replacement for pip, pip-tools, and virtualenv
• Reliable: Uses the same dependency resolution algorithm as pip
• Cross-platform: Works on macOS, Linux, and Windows
• Modern: Built in Rust for performance and safety

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run make ci to ensure all checks pass
5. Submit a pull request

Resources

• uv Documentation
• Ruff Documentation
• Pyright Documentation
• pytest Documentation