uv is worth using, let’s actually build something with it. This page walks you through creating a project from scratch, adding dependencies, understanding the files uv generates, and the different ways to run your code. By the end you’ll have a complete mental model for how uv manages your project’s environment, and you’ll be comfortable reaching for it on every new project you start.
Creating a new project
uv init creates a complete project scaffold:
The
.venv folder and uv.lock file are created automatically the first time you run uv add to install a package — not at uv init time.Understanding pyproject.toml
This single file replacesrequirements.txt, setup.py, setup.cfg, and other scattered configuration:
uv add gets recorded here automatically.
Adding packages
pyproject.toml updates itself:
The lock file
uv creates uv.lock alongside your pyproject.toml. This file records the exact version of every package (including transitive dependencies) so that anyone who clones your project and runs uv sync gets an identical environment:
Running your code
uv run is the recommended approach because it automatically uses the project’s virtual environment without any activation step.
Common uv commands
Working with existing projects
If you have a project using the oldrequirements.txt approach, uv can work with it immediately:
Virtual environment details
uv creates .venv automatically inside your project directory when you first add a package. Key things to know:
- No manual activation is needed when you use
uv run - VS Code detects
.venvautomatically and uses it for IntelliSense and the integrated terminal .venvis already in the.gitignorethatuv initcreates — don’t commit it
Tips and tricks
Install global tools (available system-wide, not per-project):pyproject.toml:
What’s next?
Ready to put the whole workflow together from start to finish?Complete setup
Start-to-finish project creation guide