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

# Python - pip, uv, Poetry

> Configure pip, uv, and Poetry to use Root Library Catalog for secure Python packages.

Root Library Catalog supports pip, uv, and Poetry. All three use the same registry endpoint and credential approach.

## Prerequisites

The Root Patcher CLI (`rootio_patcher`) is required to pull Root-secured packages into your environment. Install it before configuring your package manager.

```bash theme={null}
# macOS (Apple Silicon)
curl -sL https://github.com/rootio-avr/rootio_patcher/releases/latest/download/rootio_patcher_darwin_arm64.tar.gz | tar xz
chmod +x rootio_patcher && sudo mv rootio_patcher /usr/local/bin/

# Linux (x86_64)
curl -sL https://github.com/rootio-avr/rootio_patcher/releases/latest/download/rootio_patcher_linux_x86_64.tar.gz | tar xz
chmod +x rootio_patcher && sudo mv rootio_patcher /usr/local/bin/
```

For macOS Intel and Windows, see the [full installation instructions](/rlc/patcher#installation).

Then set your API key:

```bash theme={null}
export ROOTIO_API_KEY="your-api-key-here"
```

## Which tool should I use?

If you're starting fresh or choosing between tools, here's a quick guide:

| Tool       | Best for                                                                                                      |
| ---------- | ------------------------------------------------------------------------------------------------------------- |
| **pip**    | Simple projects, scripts, or any environment where a `requirements.txt` is sufficient                         |
| **uv**     | Fast installs, modern Python projects, `pyproject.toml`-based workflows - uv is significantly faster than pip |
| **Poetry** | Projects that need dependency locking, packaging, and publishing in one tool                                  |

All three tools read credentials from `~/.netrc` and resolve packages through `pkg.root.io/pypi/simple/`. The configuration steps differ only in how you point each tool at Root's registry.

## Authentication

All three tools read credentials from `~/.netrc`. Add your Root token:

```bash theme={null}
echo "machine pkg.root.io login token password YOUR_ROOT_TOKEN" >> ~/.netrc
chmod 600 ~/.netrc
```

***

## pip

### Configure the registry

```bash theme={null}
pip config set global.index-url https://pkg.root.io/pypi/simple &&
pip config set global.extra-index-url https://pypi.org/simple
```

### Install

Add the package to your `requirements.txt`:

```
requests==2.31.0
```

Then install:

```bash theme={null}
pip install -r requirements.txt
```

***

## uv

### Configure the registry

Add to your `pyproject.toml`:

```toml theme={null}
[[tool.uv.index]]
name = "root"
url = "https://pkg.root.io/pypi/simple/"
```

### Install and sync

```bash theme={null}
uv add requests==2.31.0
uv sync --upgrade
```

***

## Poetry

### Configure the registry

```bash theme={null}
poetry source add --priority=primary root https://pkg.root.io/pypi/simple/ &&
poetry source add --priority=supplemental pypi
```

### Install

```bash theme={null}
poetry add requests==2.31.0
poetry update
```

***

## CI/CD Configuration

Inject credentials via environment and write to `~/.netrc` at build time:

```bash theme={null}
echo "machine pkg.root.io login token password $ROOT_TOKEN" >> ~/.netrc
chmod 600 ~/.netrc
```

## Troubleshooting

| Issue              | Solution                                                                 |
| ------------------ | ------------------------------------------------------------------------ |
| `401 Unauthorized` | Verify `~/.netrc` has correct token and `chmod 600` is set               |
| Package not found  | Confirm `extra-index-url` includes PyPI as fallback                      |
| SSL errors         | Ensure you're using `https://` not `http://`                             |
| Hash mismatch      | Root serves patched packages - hashes differ from PyPI; this is expected |