RepoForge.io - Help and Support

Appearance

Using Astral UV with RepoForge ​

Astral's UV is a fast Python packaging tool that works well with RepoForge for managing private packages. This guide explains how to publish packages to RepoForge with UV and how to install packages stored in RepoForge, including the authentication options that UV supports. Follow these search-friendly steps to share and consume private Python wheels quickly.

Prerequisites ​

  • A RepoForge repository URL copied from the dashboard (for example, https://api.repoforge.io/<unique_hash_id>/). Open Python and select Show me how to publish packages to copy the full URL for your repository.
  • A RepoForge access token with Python - Full access permissions or a RepoForge username and password
  • UV installed locally (v0.2.0 or later)

Publish Python Packages to RepoForge with Astral UV ​

Follow these steps to build your project and upload it to RepoForge.

  1. Collect your RepoForge URL and token. Copy the full repository URL from the RepoForge dashboard (select Python and choose Show me how to publish packages) and make a note of it for later steps. Generate an access token with Python - Full access permissions. To reuse the token without retyping it, export it as an environment variable:

    bash
    export REPOFORGE_TOKEN="<repoforge_access_token>"

    Replace the placeholder with your actual access token and store it securely—avoid committing it to version control or sharing it in shell history.

  2. Create a sample UV project. If you do not already have a project, scaffold a basic package that prints "Hello, RepoForge!" when executed. This makes it easy to verify that publishing and installation both work.

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

    The uv init --package command scaffolds a pyproject.toml file and a package inside hello_repoforge/. Replace the default module content with a simple entry point:

    python
    # hello_repoforge/main.py
def main() -> None:
    print("Hello, RepoForge!")


if __name__ == "__main__":
    main()

  3. Configure the RepoForge index. Append a custom UV index configuration to pyproject.toml so the publish command knows how to reach your private repository. Replace the example URL with the exact RepoForge URL you copied earlier and keep the trailing slash in place.

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

    Be sure to paste the exact repository URL you copied earlier, including the trailing slash. If you embed a token in the URL for automated installs, update both url and publish-url.

  4. Build your project artifacts. UV can produce source distributions and wheels directly. Run this command from the project root:

    bash
    uv build

  5. Publish the distribution to RepoForge. Run the publish command against the named RepoForge index you just defined.

    bash
    uv publish --index repoforge

    UV prompts you for credentials when it connects to RepoForge, so enter __token__ as the username and then supply your access token when asked.

    text
    Publishing 2 files to https://api.repoforge.io/<unique_hash_id>/
Enter username ('__token__' if using a token): __token__
Enter password:

    To publish without an interactive prompt, pass the token on the command line:

    bash
    uv publish --index repoforge --token ${REPOFORGE_TOKEN}

Install RepoForge Packages with Astral UV ​

Once your packages are available in RepoForge, install them in other environments using UV.

  1. Start from a clean project. Initialize a fresh project for consuming the package so the publishing and installation environments stay separate.

    bash
    uv init hello-repoforge-consumer
cd hello-repoforge-consumer

  2. Configure the RepoForge index. Open the generated pyproject.toml and append the RepoForge index block. Replace the placeholder with your repository's actual URL, including the trailing slash.

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

  3. Set authentication environment variables. Provide your credentials through the environment so UV can reuse them without prompting.

    bash
    export UV_INDEX_REPOFORGE_USERNAME=__token__
export UV_INDEX_REPOFORGE_PASSWORD=<repoforge_access_token>

  4. Install the package from RepoForge. Use either uv add to record the dependency in pyproject.toml or uv pip install to install directly into the environment.

    bash
    uv add hello-repoforge
    bash
    uv pip install hello-repoforge

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