Using uv with RepoForge.io

Astral's uv is a fast Python packaging tool that works well with RepoForge.io for managing private packages. This guide explains how to publish packages to RepoForge.io with uv and how to install packages stored in RepoForge.io, including the authentication options that uv supports.

Prerequisites

• Your RepoForge.io Python repository URL (for example, https://api.repoforge.io/<unique_hash_id>/). You can copy it from the Get started page of the dashboard, or by selecting Python > Push package.
• A RepoForge.io access token with the Python - Full access role (to publish) or Python - Read only (to install). Create one under Access Tokens in the dashboard.
• uv installed locally. The commands on this page were checked against uv 0.13.

Publish Python packages to RepoForge.io with uv

1. Create a project

If you do not already have a project, scaffold a basic package:

uv init --package hello-repoforge
cd hello-repoforge

2. Build your project

uv build

3. Publish the distribution

There are two ways to tell uv where to publish and how to authenticate. Pick one - don't mix them.

Option A: environment variables (simplest)

Use __token__ as the username and your access token as the password:

export UV_PUBLISH_USERNAME=__token__
export UV_PUBLISH_PASSWORD=<repoforge_access_token>
export UV_PUBLISH_URL=https://api.repoforge.io/<unique_hash_id>/
uv publish

You can also pass everything on the command line, which is handy in CI:

uv publish --publish-url https://api.repoforge.io/<unique_hash_id>/ --token <repoforge_access_token>

Option B: a named index in pyproject.toml

If you'd rather configure RepoForge.io once, add an index to your pyproject.toml. Keep the trailing slash on the URLs:

[[tool.uv.index]]
name = "repoforge"
url = "https://api.repoforge.io/<unique_hash_id>/"
publish-url = "https://api.repoforge.io/<unique_hash_id>/"
authenticate = "always"

Then supply credentials with the index environment variables, and publish by index name:

export UV_INDEX_REPOFORGE_USERNAME=__token__
export UV_INDEX_REPOFORGE_PASSWORD=<repoforge_access_token>
uv publish --index repoforge

When you publish with --index, uv checks your RepoForge.io index for files that were already uploaded, and uses the index credentials (UV_INDEX_<NAME>_USERNAME / UV_INDEX_<NAME>_PASSWORD) for that check. If you combine --index with --token, --password or UV_PUBLISH_PASSWORD you will see a Missing credentials for: https://api.repoforge.io/... error. Use Option A, or the index credentials above.

Once published, refresh the Python page of the dashboard to see your package and each of its versions.

Install RepoForge.io packages with uv

1. Configure the index

In the project that will consume the package, add the RepoForge.io index to pyproject.toml:

[[tool.uv.index]]
name = "repoforge"
url = "https://api.repoforge.io/<unique_hash_id>/"
authenticate = "always"

2. Provide credentials

export UV_INDEX_REPOFORGE_USERNAME=__token__
export UV_INDEX_REPOFORGE_PASSWORD=<repoforge_access_token>

3. Install

uv add hello-repoforge

Every package page in the dashboard has an Install button which shows ready-made install snippets for pip, uv, Poetry and requirements.txt, filled in with your repository URL and the package name.

With these steps you can publish and install packages using uv while keeping your RepoForge.io credentials secure. For more background on authentication, see Authentication and permissions.