Managing Virtual Environments and Packages with uv

Learn how uv creates and manages virtual environments automatically, and how to add, remove, and update packages using the uv add and uv sync commands.

One of the best aspects of uv is that it removes most of the manual friction from virtual environment management. You no longer have to run separate commands to create a virtual environment, activate it, and then install packages. With uv, the environment is created automatically when you first add a package, activated transparently by uv run, and tracked in a lock file that makes the whole setup reproducible from a single command. This page walks you through everything you need to know to manage environments and packages the uv way.

Creating a new project

Start every new project with uv init. This creates a ready-to-use project structure in seconds:

uv init ai-assistant
cd ai-assistant

uv creates the following files:

ai-assistant/
├── .gitignore          # Pre-configured to exclude .venv, .env, __pycache__
├── .python-version     # Pins the Python version for this project
├── pyproject.toml      # Project metadata and dependencies
├── README.md           # Project description
└── main.py             # Example entry point script

The .venv folder and uv.lock file do not exist yet — they are created automatically the first time you run uv add to install a package.

Understanding pyproject.toml

pyproject.toml is the modern standard for Python project configuration. It replaces requirements.txt, setup.py, setup.cfg, and other legacy files with a single, well-structured file:

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

As you add packages, the dependencies list updates automatically. You commit this file to version control so your team always knows what the project needs.

Adding packages

Install packages with uv add:

# Add a single package
uv add requests

# Add multiple packages at once
uv add pandas numpy matplotlib

# Add a development-only dependency (not needed in production)
uv add --dev pytest

# Add ipykernel for interactive Python in VS Code
uv add ipykernel

After running uv add requests pandas numpy, your pyproject.toml updates automatically:

[project]
name = "ai-assistant"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
    "requests>=2.32.0",
    "pandas>=2.2.0",
    "numpy>=1.26.0",
]

At the same time, uv creates:

• .venv/ — the virtual environment with all packages installed
• uv.lock — the lock file with exact versions of every package and dependency

The lock file

uv.lock is one of uv’s most valuable features. It records the precise version of every package in your project — including the dependencies of your dependencies — so that uv sync always produces an identical environment:

# uv.lock (auto-generated, do not edit manually)
version = 1
requires-python = ">=3.12"

[[package]]
name = "requests"
version = "2.32.3"
dependencies = [
    { name = "certifi" },
    { name = "charset-normalizer" },
    { name = "idna" },
    { name = "urllib3" },
]

Commit uv.lock to version control. Anyone who clones your repository can run uv sync and get an environment that matches yours exactly.

Running your code

With uv, you have three ways to execute Python:

# Method 1: uv run (recommended — always uses the correct environment)
uv run python main.py

# Method 2: Activate the venv manually, then run normally
source .venv/bin/activate    # macOS / Linux
.venv\Scripts\Activate.ps1   # Windows PowerShell
python main.py

# Method 3: Use the interpreter directly
.venv/bin/python main.py     # macOS / Linux
.venv\Scripts\python.exe main.py  # Windows

Use uv run for scripts and automation. Use VS Code’s interpreter selector to pick .venv for interactive development — then VS Code manages activation for you.

Removing and updating packages

# Remove a package
uv remove requests

# Update a specific package to the latest compatible version
uv add --upgrade requests

# Update all packages
uv sync --upgrade

Reproducing an environment

When you clone a project that uses uv, get it running with a single command:

uv sync

uv reads uv.lock, creates .venv, and installs every package at the exact pinned version. No need to manually create a virtual environment or figure out which packages to install.

Working with existing pip projects

If you are migrating a project that uses requirements.txt:

# Install from requirements.txt using uv's pip compatibility layer
uv pip install -r requirements.txt

# Or import requirements.txt into pyproject.toml properly
uv add -r requirements.txt

Common uv commands reference

uv init project-name          # Create a new project
uv add package-name           # Install a package and update pyproject.toml
uv add --dev package-name     # Install a dev-only dependency
uv remove package-name        # Uninstall a package
uv sync                       # Install all dependencies from uv.lock
uv run python script.py       # Run a script in the project environment
uv pip list                   # List installed packages
uv python install 3.12        # Install a specific Python version
uv tool install black         # Install a global CLI tool

Complete project setup

Walk through a complete end-to-end project setup with uv, Git, and GitHub.