Skip to main content

Creating a new project

Let’s create a real project with uv:
This creates:
The .venv folder and uv.lock file are created automatically when you first run uv add to install packages.

Understanding pyproject.toml

This is your project’s configuration file:
It replaces:
  • requirements.txt
  • setup.py
  • setup.cfg
  • Multiple config files
One file to rule them all!

Adding packages

Add packages with uv add:
Your pyproject.toml updates automatically:

The lock file

uv creates uv.lock - this locks exact versions:
This ensures everyone gets exactly the same packages.

Running your code

Three ways to run Python with uv:
uv run is recommended - it always uses the right Python!

Common uv commands

Working with existing projects

Got a project with requirements.txt? No problem:

Virtual environment details

uv creates .venv automatically when you add packages:
  • Created on first uv add command
  • No activation needed with uv run
  • Always in project directory
  • Works with VS Code automatically
  • Already in .gitignore (uv adds it)

Tips and tricks

  1. Global tools: Install tools globally with uv
  2. Python versions: uv can manage Python too
  3. Scripts: Add custom commands

What’s next?

Ready to put it all together? Check out the complete project workflow!

Complete workflow

Start-to-finish project guide