uv Cheatsheet — Projects

·Updated March 20th, 2026
pythonuvprojectspyproject-toml

Create a New Project

bash
# Application (default — no build system)
uv init my-app
cd my-app

# Inside an existing directory
cd existing-dir
uv init

# Packaged application (with build system + src/ layout)
uv init --package my-lib

# Library (similar to --package, intended for distribution)
uv init --lib my-lib

# Specify Python version at creation time
uv init --python 3.12 my-app

# Use the uv build backend
uv init --build-backend uv my-pkg

Default Project Structure

After uv init my-app:

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

After uv init --package my-lib:

plaintext
my-lib/
├── .gitignore
├── .python-version
├── README.md
├── pyproject.toml
└── src/
    └── my_lib/
        └── __init__.py

After first uv run or uv sync, additional files appear:

plaintext
├── .venv/          # Virtual environment
└── uv.lock         # Cross-platform lockfile

The pyproject.toml

Minimal generated file:

toml
[project]
name = "my-app"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = []

For a packaged project, it also includes:

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

Or with the uv build backend:

toml
[build-system]
requires = ["uv_build>=0.7,<0.11"]
build-backend = "uv_build"

Run Your Project

bash
# Run the default entry point
uv run main.py

# Run with arguments
uv run main.py --verbose

# Run an installed executable from the environment
uv run -- pytest
uv run -- ruff check .

# Run with a specific Python version (overrides .python-version)
uv run --python 3.13 main.py

uv run automatically verifies the lockfile, syncs the environment, then executes. No manual activate needed.

Sync the Environment

bash
# Install all dependencies from the lockfile
uv sync

# Include optional dependency groups
uv sync --group dev --group test

# Install all groups
uv sync --all-groups

# Sync without dev dependencies
uv sync --no-dev

# Freeze — don't update the lockfile first
uv sync --frozen

Lock Dependencies

bash
# Regenerate the lockfile
uv lock

# Check lockfile is consistent (CI-friendly)
uv lock --check

# Upgrade everything to latest compatible
uv lock --upgrade

# Upgrade a single package
uv lock --upgrade-package requests

Manual Virtual Environment Activation

If you prefer to activate the venv instead of using uv run:

bash
uv sync
source .venv/bin/activate   # bash/zsh
# .venv/bin/activate.fish   # fish

Read Project Version

bash
uv version
# 0.1.0

# Set a new version
uv version 1.0.0