> ## Documentation Index
> Fetch the complete documentation index at: https://fastapi2day.codewithsiva.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# 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:
```bash theme={null}
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:
```toml theme={null}
[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`:
```bash theme={null}
# 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:
```toml theme={null}
[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:
```toml theme={null}
# 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:
```bash theme={null}
# 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
```bash theme={null}
# 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:
```bash theme={null}
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`:
```bash theme={null}
# 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
```bash theme={null}
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
```
Walk through a complete end-to-end project setup with uv, Git, and GitHub.