Post

UV: Python Project & Environment Manager

Discover UV, a lightweight Python tool that simplifies project and environment management.

UV: Python Project & Environment Manager
📑 Table of Contents

uv is a modern CLI tool written in Rust, designed to manage Python projects, virtual environments, dependencies, and project scripts in a unified way. Even though it’s written in Rust, it interacts seamlessly with Python because it manages .venv environments, Python interpreters, and dependencies directly.

Why use UV

  • Provides automatic virtual environment management.
  • Handles dependency installation (uv add) without manual activation of .venv.
  • Supports running commands in the project environment (uv run).
  • Manages Python versions (uv python install <version> / uv python pin).
  • Acts as a unified tool for project scaffolding, dependency management, and running scripts.

Installation Methods

MethodWhat it does
curl -LsSf https://astral.sh/uv/install.sh | shInstalls UV globally via Rust binary
pip install uvInstalls UV in the current Python environment
pipx install uvInstalls UV globally in an isolated environment

Upgrading uv

  • if installed Using curl
    • Rerun the install script to replace the binary.
  • Using pip/pipx

    1
    2
    3
    4
    5
    
      # if installed via pip
      pip install --upgrade uv
    
      # if installed via pipx
      pipx upgrade uv
    

uv Behavior with .venv

If a .venv folder exists in the same directory as pyproject.toml, uv will:

  • Use that .venv for Python interpreter and dependencies.
  • Run commands and install libraries in that environment automatically.

If .venv does not exist, uv will create it when you run:

1
uv venv

No explicit activation is needed for uv add or uv run commands, though activating .venv is best practice.


uv and .venv: Pip vs uv Behavior

CAUTION
If you use uv venv to create a .venv, do not use pip directly, even if you activate the environment with:
source .venv/bin/activate
Using pip may install packages into the system Python, not the .venv.


1️⃣ .venv created by uv venv

1
uv venv

uv creates a virtual environment under .venv using Python.

It sets up Python interpreter binaries and a standard venv folder structure, but it does not install or link a system pip automatically in the same way Python does.

uv then expects you to use uv commands (uv add <package>) to install packages.

✅ uv add requests → works inside .venv
❌ pip install requests → might fail or install into system Python, because uv’s .venv is intended to be managed via uv and may not have pip properly bootstrapped for direct use.

In short: uv created venv is “uv-controlled”, not a standard Python-managed venv for pip.

If you want to use pip safely, create the environment via:

1
python -m venv .venv

In a pip-created .venv, both uv and pip work seamlessly.


2️⃣ .venv created by python -m venv .venv

1
source .venv/bin/activate

This is a standard Python virtual environment.

It includes its own pip inside .venv/bin/pip.

You can now freely do:

1
2
pip install requests
python -m pip install fastapi

uv can also use this .venv:

1
2
uv add some_package
uv run python script.py

Both uv and pip install into the same .venv, because pip exists in that environment.


Rule of Thumb
  • uv created venv → use uv commands only
  • pip-created venv → use pip or uv commands

Activating the environment with source .venv/bin/activate does not magically fix uv venv for pip if pip wasn’t installed.

If you want pip in a uv venv, you would need to bootstrap pip manually:

1
2
3
uv venv
.venv/bin/python -m ensurepip --upgrade
pip install <package>

Key Commands

CommandDescription
uv initInitializes the entire project structure including pyproject.toml
uv venvCreates a .venv folder at the current directory level; optionally: uv venv --python python3.13 to choose a Python version
uv add <package>Installs a dependency into .venv
uv run <command>Runs a command inside the .venv environment
uv python install <version>Installs a specific Python version
uv python pin <version>Pins the project to use a specific Python version
uv tool install <tool>Installs CLI tools like ruff without polluting the environment

Important notes about .venv & pyproject.toml

  • .venv must exist at the same level as pyproject.toml.
  • Activating .venv ensures that uv uses the correct Python interpreter.
  • Running uv add <package> outside the directory containing pyproject.toml will not work.

Example directory:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
/home/project/
├── .venv
└── pyproject.toml

# Inside project directory:

uv add requests   # Works fine
uv run python main.py

# Outside project directory:

cd ..
uv run python main.py   # Won’t work, as pyproject.toml is not found

# Activating `.venv`:

source .venv/bin/activate
uv run python --version   # Ensures correct Python from `.venv` is used

Example Python interpreter behavior

1
2
3
4
5
6
7
8
9
10
11
12
# Inside project without activating
uv run which python --version
# /home/user/workspace/project/.venv/bin/python

# Outside project
uv run which python --version
# Returns system Python (uv can’t find pyproject.toml/.venv)

# After activating .venv
source .venv/bin/activate
uv run which python --version
# /home/user/workspace/project/.venv/bin/python

Takeaway: Activation ensures uv picks the correct Python version, but uv can work without activation if .venv exists in the same folder as pyproject.toml.


Flow for creating a project with uv

  1. Create a project:
1
2
uv init myproject
cd myproject
  1. Create virtual environment:
1
uv venv --python python3.13
  1. Add dependencies:
1
uv add requests fastapi
  1. Run Python scripts inside the environment:
1
uv run python main.py
  1. Upgrade uv if needed:
1
2
curl -LsSf https://astral.sh/uv/install.sh | sh   # curl installer
pipx upgrade uv                                     # if pipx-installed

Summary of uv behavior

  • .venv must be in the same folder as pyproject.toml.
  • uv will automatically use .venv for running commands and installing dependencies.
  • No manual activation is strictly required, but recommended for safety.
  • Avoid using system pip directly — always use uv add inside the project.
This post is licensed under CC BY 4.0 by the author.