Skip to main content

​
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: 
uv init hello-world
cd hello-world
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

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.
Specifies the default Python version for your project. uv uses this file to determine which Python version to use when creating the virtual environment.
Contains your project’s isolated Python environment where dependencies are installed. See the project environment documentation for more details.
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:
uv add 'requests==2.31.0'
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: 
uv sync
source .venv/bin/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: 
uv version
# hello-world 0.7.0
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

Build docs developers (and LLMs) love

Get started for freeTalk to us