> ## Documentation Index
> Fetch the complete documentation index at: https://aegean.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Python Package Management with uv

> Installing Python, managing dependencies, and working with virtual environments using uv.

This course uses [uv](https://docs.astral.sh/uv/) for all Python dependency management. Written in Rust, uv is 10-100x faster than pip and replaces multiple tools, pip, pip-tools, pipx, poetry, pyenv, and virtualenv, with a single binary.

## Installing uv

<Tabs>
  <Tab title="macOS / Linux">
    ```bash theme={null}
    curl -LsSf https://astral.sh/uv/install.sh | sh
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
    ```
  </Tab>

  <Tab title="Homebrew">
    ```bash theme={null}
    brew install uv
    ```
  </Tab>
</Tabs>

<Note>
  Inside the course Docker containers, uv is already installed. You only need to install it locally if you are working outside Docker.
</Note>

## Managing Python versions

uv can install and manage Python versions directly, no need for pyenv or system package managers:

```bash theme={null}
# Install a specific Python version
uv python install 3.12

# Pin the Python version for your project
uv python pin 3.12

# List installed versions
uv python list
```

## Virtual environments

uv creates and manages virtual environments:

```bash theme={null}
# Create a virtual environment
uv venv

# Create with a specific Python version
uv venv --python 3.12

# Create with access to system packages (used in course containers)
uv venv --system-site-packages
```

The virtual environment is created in `.venv/` by default. Activate it with:

```bash theme={null}
source .venv/bin/activate
```

<Warning>
  Do not commit the `.venv` folder to your GitHub repo. The repository's `.gitignore` already excludes it.
</Warning>

## Installing packages

uv provides a pip-compatible interface for installing packages:

```bash theme={null}
# Install a package
uv pip install numpy

# Install from pyproject.toml
uv pip install -e .

# Install with extras (e.g., notebooks, dev)
uv pip install -e ".[notebooks]"

# Install with a constraints file
uv pip install -e . --constraint constraints.txt
```

## Project management

For projects with a `pyproject.toml` (like the course repository), uv provides higher-level commands:

```bash theme={null}
# Add a dependency to the project
uv add pandas

# Add a dev dependency
uv add --dev pytest

# Lock dependencies (creates uv.lock)
uv lock

# Sync environment to match the lockfile
uv sync

# Run a script in the project environment
uv run python train.py
```

The `uv.lock` file is a cross-platform lockfile that ensures reproducible installs across machines and operating systems.

## Course workflow

Inside the course Docker container, dependencies are pre-installed. The typical workflow is:

```bash theme={null}
# Set up the environment (first time)
make start

# Install the package with notebook extras
make install-notebooks

# Or manually:
uv pip install -e ".[notebooks]"
```

If you need to add a package for your assignment or project:

```bash theme={null}
# Inside the container
uv pip install <package>
```

## Why uv over pip or conda

|                       | uv                             | pip                               | conda                                 |
| --------------------- | ------------------------------ | --------------------------------- | ------------------------------------- |
| **Speed**             | 10-100x faster                 | Baseline                          | Slower                                |
| **Lockfiles**         | Cross-platform `uv.lock`       | No built-in lockfile              | `environment.yml` (not locked)        |
| **Python management** | Built-in (`uv python install`) | Requires pyenv or system packages | Built-in                              |
| **Virtual envs**      | Built-in (`uv venv`)           | Requires virtualenv               | Built-in                              |
| **Disk usage**        | Global cache, deduplication    | Per-environment copies            | Large per-environment copies          |
| **NVIDIA containers** | Compatible                     | Compatible                        | Conflicts with pre-installed packages |

<Tip>
  Avoid conda environments in this course. They conflict with the optimized NVIDIA containers and create dependency resolution issues with pre-installed PyTorch packages.
</Tip>

## Useful commands reference

| Command                         | Description                              |
| ------------------------------- | ---------------------------------------- |
| `uv pip install <pkg>`          | Install a package                        |
| `uv pip install -e ".[extras]"` | Install project with extras              |
| `uv pip compile pyproject.toml` | Generate locked requirements             |
| `uv pip sync requirements.txt`  | Sync environment to requirements         |
| `uv add <pkg>`                  | Add a dependency to `pyproject.toml`     |
| `uv lock`                       | Create/update the lockfile               |
| `uv sync`                       | Sync environment to lockfile             |
| `uv run <command>`              | Run a command in the project environment |
| `uv venv`                       | Create a virtual environment             |
| `uv python install <version>`   | Install a Python version                 |
| `uv python pin <version>`       | Pin Python version for the project       |
| `uv tool run <tool>`            | Run a tool in an ephemeral environment   |

For the full documentation, see [docs.astral.sh/uv](https://docs.astral.sh/uv/).

***

<Callout icon="pen-to-square" iconType="regular">
  [Edit this page on GitHub](https://github.com/aegean-ai/eaia/edit/main/src/aiml-common/resources/environment/python-uv.mdx) or [file an issue](https://github.com/aegean-ai/eaia/issues/new/choose).
</Callout>