Python uv Project Template

A minimal Python project template using uv - an extremely fast Python package and project manager, written in Rust.
Just clone this repo, install uv with pip install uv and run uv run main

Project Structure

project_name/
├── pyproject.toml            # Project configuration and dependencies
├── src/
│   └── project_name/         # Must match name in pyproject.toml
│       ├── __init__.py
│       ├── main.py           # Main entry point
│       └── moduleA/          # Package name
│           ├── __init__.py
│           └── operations.py # Module
│
├── tests       # Tests location: uv run pytest
├── uv.lock     # Exact dependency versions (auto-created by uv)
└── .venv/      # Virtual environment (auto-created by uv)

Key Files Explained

• pyproject.toml: Central configuration file defining your project, dependencies, and scripts
• uv.lock: Lock file that pins exact dependency versions for reproducible builds
• src/project_name/: Source code directory following Python packaging standards
• .venv/: Virtual environment automatically created and managed by uv

What is uv?

uv is a modern Python package and project manager designed to be a faster, simpler alternative to traditional tools like pip and virtualenv. It:

• Automatically manages virtual environments - no more manual venv creation
• Resolves dependencies faster - up to 10-100x faster than pip
• Uses modern standards - fully compliant with PEP 621 (pyproject.toml)

Why use uv instead of pip/virtualenv?

Traditional Workflow	uv Workflow
python -m venv .venv	uv sync
source .venv/bin/activate	(automatic)
pip install -r requirements.txt	(handled by uv sync)
python script.py	uv run python script.py

Quick Start Guide

1. Install uv

pip install uv

2. Set Up Your Project

# In your project root
uv sync

What uv sync does:

• Creates a virtual environment (.venv/)
• Installs all dependencies from pyproject.toml
• Updates the uv.lock file with exact versions

Running Your Project

Method 1: Using uv run

# Run the main script
uv run src/project_name/main.py

# Run any module
uv run python -m project_name.main
uv run python -m project_name.moduleA.operations

Why use uv run?

• Automatically uses the project's virtual environment
• No need to manually activate/deactivate environments
• Works consistently across different operating systems

Method 2: Using Script Shortcuts

Define convenient scripts (aliases) in pyproject.toml:

[project.scripts]
main = "project_name.main:main"
moduleA = "project_name.moduleA.operations:main"

Run them directly:

# Run the main script
uv run main

# Run the moduleA script
uv run moduleA

Method 3: Direct Python Execution

# Option 1: Run as a module
python -m project_name.main

# Option 2: Run the Python file directly
python src/project_name/main.py

Activating the virtual environment

Note: For direct execution, make sure you've activated the virtual environment first:

# macOS and Linux
source .venv/bin/activate

# Windows (Command Prompt)
.venv\Scripts\activate

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

Managing Dependencies

uv makes dependency management simple and intuitive.

Adding New Dependencies

# Add multiple packages at once
uv add requests pytest

# Add as development dependencies
uv add --dev pytest

What happens when you add a package:

• Updates pyproject.toml with the new dependency
• Updates uv.lock with the exact version
• Installs the package in the virtual environment

Removing Dependencies

# Remove a package
uv remove requests

# Remove development dependencies
uv remove --dev pytest

Updating Dependencies

# Update all dependencies to latest compatible versions
uv sync --upgrade

# Update a specific package
uv add --upgrade requests

# Update only dev dependencies
uv sync --upgrade --dev

Checking Installed Packages

# List all installed packages
uv pip list

# Show dependency tree
uv pip tree

# Check for outdated packages
uv pip list --outdated

Development Workflow

Virtual Environment Management

Reminder: uv run <cmd> will run the <cmd> in the virtual environment but not load the environment into the terminal.
If desired, to activate the virtual environment check the uv docs for linux, windows, fish.

uv run pip -> uses the .venv
pip -> uses the main python environment
source .venv/bin/activate && pip -> pip now uses the .venv

# Create a new virtual environment
uv venv

# Use a specific Python version
uv venv --python 3.11

# Remove the virtual environment
uv venv --delete

Best Practices

1. Always use uv sync after cloning - ensures all dependencies are installed
2. Commit uv.lock to version control - ensures reproducible builds
3. Use uv add and uv remove - don't edit pyproject.toml manually
4. Run commands with uv run - avoids environment activation issues
5. Regularly update dependencies - uv sync --upgrade to get security updates

Troubleshooting

If you encounter issues:

1. Check uv documentation: https://docs.astral.sh/uv/
2. Run with verbose output: uv --verbose sync
3. Check for known issues: https://github.com/astral-sh/uv/issues

Creating Standalone Executables

Build you package as a .whl or .exe

# Package your application
uv build

# Create a standalone executable
uv pip install PyInstaller
uv run python -m PyInstaller --onefile src/project_name/main.py