Working with Projects

A complete guide to creating and managing Python projects with uv

Overview

uv supports managing Python projects with dependencies defined in pyproject.toml. This guide covers the full workflow from initialization to deployment.

Creating a new project

You can create a new Python project using uv init:

Create in new directory

uv init hello-world
cd hello-world

mkdir hello-world
cd hello-world
uv init

uv creates the following files:

├── .gitignore
├── .python-version
├── README.md
├── main.py
└── pyproject.toml

Test your new project:

uv run main.py
# Output: Hello from hello-world!

Project structure

After running your first project command (uv run, uv sync, or uv lock), uv creates additional files:

.
├── .venv
│   ├── bin
│   ├── lib
│   └── pyvenv.cfg
├── .python-version
├── README.md
├── main.py
├── pyproject.toml
└── uv.lock

Key files explained

pyproject.toml - Project metadata

Contains your project’s dependencies and metadata:

[project]
name = "hello-world"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
dependencies = []

You can edit this file manually or use commands like uv add and uv remove.

See the official pyproject.toml guide for more details.

.python-version - Python version pinning

Specifies the default Python version for your project. uv uses this file to determine which Python version to use when creating the virtual environment.

.venv - Virtual environment

Contains your project’s isolated Python environment where dependencies are installed. See the project environment documentation for more details.

uv.lock - Lockfile

A cross-platform lockfile with exact dependency versions. Unlike pyproject.toml (which specifies broad requirements), the lockfile contains exact resolved versions.

This file is human-readable TOML but managed by uv — don’t edit it manually.

Always commit uv.lock to version control for consistent installations across machines.

Managing dependencies

1. Add a dependency

   Add packages to your project with uv add:

   uv add requests
   

   This updates pyproject.toml, uv.lock, and your virtual environment.

2. Add version constraints

   Specify version constraints or alternative sources:

   Specific version

   uv add 'requests==2.31.0'
   

   uv add git+https://github.com/psf/requests
   
3. Migrate from requirements.txt

   Import all dependencies from an existing requirements file:

   uv add -r requirements.txt -c constraints.txt
   
4. Remove dependencies

   Remove packages you no longer need:

   uv remove requests
   
5. Upgrade packages

   Update specific packages to the latest compatible version:

   uv lock --upgrade-package requests
   

   The --upgrade-package flag updates the specified package while keeping the rest of the lockfile intact.

Running commands

uv run executes scripts or commands in your project environment:

# Run a Python script
uv run example.py

# Run a tool (uv adds it first if needed)
uv add flask
uv run -- flask run -p 3000

uv run automatically syncs your environment before execution, ensuring dependencies match uv.lock.

Using the project environment directly

Alternatively, manually sync and activate the environment:

macOS / Linux

uv sync
source .venv/bin/activate
flask run -p 3000
python example.py

uv sync
.venv\Scripts\activate
flask run -p 3000
python example.py

The virtual environment must be active to run scripts without uv run. Activation differs per shell and platform.

Viewing your version

Check your package version:

Full output

uv version
# hello-world 0.7.0

uv version --short
# 0.7.0

uv version --output-format json
# {
#     "package_name": "hello-world",
#     "version": "0.7.0",
#     "commit_info": null
# }

See the publishing guide for details on updating your version.

Building distributions

Build source distributions and wheels for your project:

uv build

By default, artifacts are placed in a dist/ subdirectory:

ls dist/
# hello-world-0.1.0-py3-none-any.whl
# hello-world-0.1.0.tar.gz

See the building projects documentation for more details.

Complete workflow example

Here’s a complete project workflow from initialization to building:

1. Initialize project

   uv init my-app
   cd my-app
   
2. Add dependencies

   uv add fastapi uvicorn
   
3. Write your code

   Create your application in main.py:

   from fastapi import FastAPI
   
   app = FastAPI()
   
   @app.get("/")
   def read_root():
       return {"message": "Hello from my-app!"}
   
4. Run your application

   uv run uvicorn main:app --reload
   
5. Add development dependencies

   uv add --dev pytest pytest-cov
   
6. Build for distribution

   uv build
   

Next steps

Projects concept

Learn more about how uv projects work

Export lockfiles

Export to different formats

Running scripts

Learn about standalone Python scripts

Command reference

View all uv commands