This tutorial shows you how to configure uv to install Python packages from a private PyPI repository on RepoForge.io.

What is uv?

uv is an extremely fast Python package installer and resolver, written in Rust by Astral (the creators of Ruff). It’s a drop-in replacement for pip and pip-tools that’s 10-100x faster.

Prerequisites

  • A RepoForge.io account
  • Your RepoForge repository URL (found under Show me how to publish packages)
  • An access token with Python read permissions
  • A package already published to your RepoForge repository

Installing uv

Install uv using the official installer:

curl -LsSf https://astral.sh/uv/install.sh | sh

Or with pip:

pip install uv

Verify the installation:

uv --version

Configuring Authentication

uv supports the same authentication methods as pip. The recommended approach is to use an access token.

Option 1: Environment Variable

Set the UV_EXTRA_INDEX_URL environment variable with your credentials embedded:

export UV_EXTRA_INDEX_URL=https://__token__:your-access-token@api.repoforge.io/your-hash-id/

Option 2: pip.conf

uv reads pip’s configuration file. Add your RepoForge repository to ~/.config/pip/pip.conf (Linux/macOS) or %APPDATA%\pip\pip.ini (Windows):

[global]
extra-index-url = https://__token__:your-access-token@api.repoforge.io/your-hash-id/

Option 3: pyproject.toml (per-project)

For project-specific configuration, add the source to your pyproject.toml:

[tool.uv]
extra-index-url = ["https://__token__:your-access-token@api.repoforge.io/your-hash-id/"]

Security note: Avoid committing credentials to version control. Use environment variables in CI/CD pipelines.

Installing Packages

Once configured, install packages from your private repository:

uv pip install my-private-package

Or with a requirements file:

uv pip install -r requirements.txt

uv will automatically check both PyPI and your private RepoForge repository when resolving dependencies.

Using with uv Projects

If you’re using uv’s project management features, add dependencies directly:

uv add my-private-package

This will update your pyproject.toml and uv.lock files.

Using in Docker

For Docker builds, pass the credentials as a build argument:

FROM python:3.12-slim

ARG REPOFORGE_ACCESS_TOKEN

RUN pip install uv

ENV UV_EXTRA_INDEX_URL=https://__token__:${REPOFORGE_ACCESS_TOKEN}@api.repoforge.io/your-hash-id/

COPY requirements.txt .
RUN uv pip install --system -r requirements.txt

Build with:

docker build --build-arg REPOFORGE_ACCESS_TOKEN=your-access-token -t myapp .

Using in CI/CD

For GitHub Actions, store your access token as a secret and configure uv:

- name: Install dependencies
  env:
    UV_EXTRA_INDEX_URL: https://__token__:${{ secrets.REPOFORGE_TOKEN }}@api.repoforge.io/your-hash-id/
  run: |
    pip install uv
    uv pip install --system -r requirements.txt

Troubleshooting

401 Unauthorized

  • Verify your access token has Python read permissions
  • Check the token hasn’t expired or been revoked
  • Ensure you’re using __token__ as the username

Package not found

  • Confirm the package exists in your RepoForge repository
  • Check the package name matches exactly (case-sensitive)
  • Verify your repository URL is correct

Your private Python packages can now be installed with uv’s speed and reliability.