openhands/uv

uv (Python)

Use uv as the default tool for Python dependency + environment management when the repo has uv.lock, mentions uv in its docs/Makefile, or already uses a .venv created by uv.

Quick decision rules

• If the repo has uv.lock and pyproject.toml: treat it as a uv-managed project.
• If the repo has only requirements.txt: you can still use uv pip for fast installs.
• Prefer project commands (uv add/remove/sync/run/lock) over raw pip unless the repo explicitly uses uv pip.

Installation (if needed)

Prefer a packaged install method when available. If you use the official installer, review it first (avoid blindly piping into a shell) and follow the latest instructions in the official docs.

# macOS/Linux (official installer)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell, official installer)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Common operations

Initialize a new project

uv init
# or
uv init my-project

Create / use a virtual environment

uv venv  # creates .venv

# If you need a specific version, match the project's declared requirement
# (e.g., pyproject.toml / CI config), not an arbitrary latest version.
uv venv --python 3.x

# optional activation (not required for uv commands)
source .venv/bin/activate  # macOS/Linux
# .venv\\Scripts\\activate   # Windows

Add / remove dependencies (updates pyproject.toml and uv.lock)

uv add requests
uv add 'requests==2.31.0'
uv add -r requirements.txt

uv remove requests

Lock + sync (reproducible installs)

uv lock   # (re)generate uv.lock
uv sync   # create/update .venv to match uv.lock

If you pulled new changes and uv.lock changed, run uv sync.

Run commands inside the project environment

uv run python -m pytest -q
uv run python main.py
uv run ruff check .

Using uv as a fast pip replacement (requirements workflows)

uv venv
uv pip install -r requirements.txt
uv pip freeze
uv pip list

Notes / pitfalls

• uv will usually auto-detect and use .venv in the project root.
• In CI/containers you may see uv pip install --system, but prefer virtualenvs for local dev.
• If a command mutates deps, prefer uv add/remove/lock/sync so uv.lock stays correct.