uv - package and project manager

Short tutorial on uv: https://earthly.dev/blog/python-uv/

---

General

uv is a fast Python package and project manager written in Rust. uv is a single tool designed to be a high-speed replacement for multiple Python development tools. It integrates the functionalities of packages like pip, pip-tools, pipx, poetry, pyenv, and virtualenv into one command-line interface.

Key Features

• Speed: 10-100x faster than pip

• Lock files: uv.lock for reproducible installs

• Universal: Works across projects and Python versions

• No separate pip/venv/virtualenv: All-in-one tool

Configuration Files

• pyproject.toml: Project metadata and dependencies

• uv.lock: Locked dependencies (like package-lock.json)

• .python-version: Pinned Python version

uvx is for running Python tools in isolated environments.

UVX as a Python tool (uvx)

• Function: UVX is a command for the uv Python tool that lets you run other Python tools without installing them globally.

• Process: When you run uvx <tool>, it automatically creates a temporary, isolated Python environment, installs the tool, runs it, and then cleans up the environment.

• Benefit: This prevents polluting your system with temporary dependencies and avoids potential version conflicts.

• Alias: uvx is a convenient alias for the uv tool run command.

Nice overview of commands: https://docs.astral.sh/uv/getting-started/features/#python-versions

---

Common Workflows

Start new project:

uv init my-project
cd my-project
uv add requests  # Add dependencies
source .venv/bin/activate
uv run python main.py

What does uv init command do for you?

Normal uv init command creates these files and directories:

• .python-version is the file which contains the python version this project is configured to use.

  • Pins the Python version for the project

  • Used by uv to automatically use the right Python

  • Can be changed with uv python pin <version>

• .git directory

• .gitignore file

• main.py Python file

• pyproject.toml is the configuration file for your project

  • Project metadata and configuration

  • Dependencies go in the dependencies = [] array

  • Standard Python packaging file (PEP 621)

• README.md

uv init --app is the equivalent of uv init and is the default option.

uv init --lib # Create library project
uv init --app # Create application project

uv add command

• adds dependencies to your project

• creates a virtual environment with .venv directory

• creates a uv.lock file with exact versions of added dependencies.

• run source .venv/bin/activate after uv add

What does uv run do?

It runs tools in project environment

uv run script.py # Run script in project environment
uv run python # Start Python REPL
uv run pytest # Run tools in project environment

Issues:

• ❌ Inconsistent versions across team members

• ❌ Tool version might not match project needs

• ❌ CI/CD might have different versions

• ❌ Hard to reproduce issues

Benefits:

• ✅ Reproducibility: Everyone uses same tool versions

• ✅ Isolation: Tool dependencies don't conflict with project

• ✅ Version control: Tool versions in pyproject.toml

• ✅ CI/CD consistency: Same environment everywhere

Hence, no "works on my machine" problems.

---

What do uv pip commands do?

uv pip is a drop-in replacement for pip, but much faster (10-100x).

Basic Commands

# Installation
uv pip install package              # Install a package
uv pip install package==1.2.3       # Specific version
uv pip install "package>=1.0,<2.0"  # Version range
uv pip install -r requirements.txt  # From requirements file
uv pip install -e .                 # Editable install (development)

# Uninstallation
uv pip uninstall package            # Remove package
uv pip uninstall -r requirements.txt

# Information
uv pip list                         # List installed packages
uv pip show package                 # Show package details
uv pip freeze                       # Output installed packages
uv pip freeze > requirements.txt    # Export to file

# Other
uv pip check                        # Verify dependencies
uv pip compile pyproject.toml       # Generate requirements.txt

✅ Use when:

• Working with legacy projects using requirements.txt

• Need pip-compatible workflow

• Installing packages in existing venv

• One-off installations

❌ Don't use when:

• Starting new projects (use uv add instead)

• You want lock files (use uv project commands)

---

What is a lock file?

A lock file (uv.lock) is a detailed snapshot of every single dependency with exact versions used in your project.

uv add requests           # Automatically creates/updates uv.lock
uv lock                   # Manually update lock file                # Manually update lock file

Installation

uv sync                   # Install from lock file (exact versions)
uv sync --frozen          # Install without updating lock (CI/CD)

The Problem Lock Files Solve

Without lock file:

# pyproject.toml
dependencies = [
    "requests>=2.28.0"
]
```

❌ **Issues:**
- **Today**: You install `requests==2.28.0`, which depends on `urllib3==1.26.0`
- **Next week**: Your coworker installs and gets `requests==2.31.0` with `urllib3==2.0.0`
- **Result**: Different environments, potential bugs, "works on my machine"

**With lock file:**
```
# uv.lock captures EXACT versions
requests==2.28.0
urllib3==1.26.0
certifi==2023.7.22
charset-normalizer==3.2.0
idna==3.4

✅ Everyone gets identical dependencies

---

Direct vs Transitive Dependencies

Direct dependencies (you explicitly added):

uv add requests pytest

Transitive dependencies (pulled in automatically):

• requests needs urllib3, certifi, charset-normalizer, idna

• Lock file captures all of them

---

Lock File vs Requirements

File	Purpose	Audience
pyproject.toml	High-level requirements	Humans
uv.lock	Exact resolved versions	Machines

pyproject.toml:

dependencies = ["flask>=2.0"]  # Flexible range

uv.lock:

flask==3.0.0                   # Exact version
werkzeug==3.0.1               # + all transitive deps
jinja2==3.1.2
click==8.1.7
# ... etc

---

Updating Dependencies

uv lock --upgrade          # Update all to latest compatible versions
uv lock --upgrade-package pandas  # Update just pandas

Committing to Git

git add pyproject.toml uv.lock  # ✅ ALWAYS commit lock file
git add .venv/                  # ❌ NEVER commit venv

---

Best Practices for uv.lock files

✅ DO:

• Commit uv.lock to git

• Use uv sync --frozen in CI/CD

• Regularly update with uv lock --upgrade

• Review lock file changes in PRs

❌ DON'T:

• Manually edit uv.lock

• Delete lock file to "fix" issues

• Use different lock files for dev/prod

• Commit .venv/ directory

Real-world example

Developer A (Monday):

uv init my-app
uv add flask sqlalchemy
git commit -am "Initial setup"
# uv.lock: flask==3.0.0, sqlalchemy==2.0.23

Developer B (Friday):

git clone my-app
uv sync                     # Gets flask 3.0.0, sqlalchemy 2.0.23
uv run python app.py        # Works identically!

Without lock file, Developer B might get flask==3.1.0 and sqlalchemy==2.0.25, causing subtle bugs.

The lock file is your time machine for dependencies! 🔒

---

--frozen option in uv sync command for CI/CD scenarios

What --frozen Does

uv sync --frozen

Behavior:

1. ✅ Installs dependencies from uv.lock (exact versions)

2. ❌ Refuses to update uv.lock

3. ❌ Fails if lock file is out of sync with pyproject.toml

Scenario: Developer Forgot to Update Lock

# Developer locally:
vim pyproject.toml          # Manually adds "requests>=2.28"
git add pyproject.toml
git commit -m "Add requests"
git push
# ❌ Forgot to run `uv lock` or `uv add requests`

In CI/CD:

uv sync --frozen
# ❌ ERROR: pyproject.toml has 'requests' but uv.lock doesn't
# Build FAILS ✋

---

Integrations

• Using uv with AWS Lambda

• uv with Docker

• uv with Github Actions

• uv with Gitlab CI/CD

---

Setup UV environment variables

https://docs.astral.sh/uv/reference/environment/

---

Authentication with UV

https://docs.astral.sh/uv/concepts/authentication/

---

About caching

Caching | uvdocs.astral.sh

---