Skip to main content

​
Authenticating the uv client

pyx is supported as a first-class package registry in the uv client as of uv v0.8.15. You can install uv with our standalone installers, or with your package manager of choice: 
curl -LsSf https://astral.sh/uv/install.sh | sh
Once installed, you can authenticate the uv client with: 
uv auth login pyx.dev
This will open a browser window to authenticate via the pyx dashboard. By default, uv supports OAuth-based authentication via GitHub and Google. For SSO support, get in touch.
If you’re running in a headless environment, e.g., when SSH’d into a remote server, you’ll be prompted to open a browser window to authenticate.
uv also supports API key-based authentication. You can create API keys in the pyx dashboard and authenticate the client by setting the PYX_API_KEY environment variable: 
export PYX_API_KEY=sk-pyx-...
To verify that you’ve authenticated successfully, you can install a package from the pyx PyPI mirror with: 
uv pip install ruff --default-index https://api.pyx.dev/simple/pypi
You can un-authenticate the uv client with: 
uv auth logout pyx.dev
Logging out will invalidate the refresh token on the server and remove the cached credentials from the machine.

​
Authenticating external tools

pyx uses JWT-based authentication. When authenticating via the uv auth login command, uv will store a JWT token on your machine, alongside a refresh token. When making API requests, uv will include the JWT token in the Authorization header. If the JWT token is expired, uv will automatically refresh it using the refresh token. When authenticating via PYX_API_KEY, uv will perform a similar process, but without the need for a refresh token. If necessary, you can use uv auth token pyx.dev to generate a JWT token for use with the pyx API: 
❯ uv auth token pyx.dev
eyJhbGciOiJIU...
This will print a JWT token (with a 1-hour expiry) that you can use to authenticate external tools. For example, you can use the token to view the package metadata for ruff with: 
curl -H "Authorization: Bearer $(uv auth token pyx.dev)" https://api.pyx.dev/simple/pypi/ruff
For compatibility, pyx also supports HTTP Basic authentication by setting the username to __token__ and the password to the JWT token, e.g.: 
curl -u __token__:$(uv auth token pyx.dev) https://api.pyx.dev/simple/pypi/ruff
In rare cases, it may also be useful to authenticate uv itself with a short-lived JWT rather than an API key by setting the PYX_AUTH_TOKEN environment variable: 
export PYX_AUTH_TOKEN=$(uv auth token pyx.dev)

​
Authenticating with Docker

In Docker builds, we recommend using Docker’s built-in support for build secrets. When invoking docker buildx build, you can pass an API key as a build secret. For example, assuming that your API key is stored in the PYX_API_KEY environment variable, you can pass it as a build secret with: 
docker buildx build --secret id=pyx_api_key,env=PYX_API_KEY
In the Dockerfile, you can then reference the pyx_api_key build secret as follows: 
RUN --mount=type=secret,id=pyx_api_key,env=PYX_API_KEY \
    --mount=type=cache,target=/root/.cache/uv \
    uv sync
To authenticate a Docker build without an API key (i.e., from a logged-in uv client), you can generate an access token with uv auth token pyx.dev and pass it to Docker as a build secret: 
PYX_AUTH_TOKEN=$(uv auth token pyx.dev) && \
    docker buildx build --secret id=pyx_auth_token,env=PYX_AUTH_TOKEN
In the Dockerfile, you can then reference the pyx_auth_token build secret as follows: 
RUN --mount=type=secret,id=pyx_auth_token,env=PYX_AUTH_TOKEN \
    --mount=type=cache,target=/root/.cache/uv \
    uv sync
Build secrets do not persist across builds, and do not invalidate layer caches. As such, re-running a Docker build with a regenerated access token will retain the cached layers from the previous build.
If you use Docker’s docker/build-push-action GitHub Action, you can pass the API key as a build secret to the action directly: 
- name: Build and Push
  uses: docker/build-push-action@v5
  with:
    secrets: |
      pyx_api_key=${{ secrets.PYX_API_KEY }}
    context: .
    file: Dockerfile
    push: true
    tags: ...

​
Authenticating with Bazel

Bazel versions 7 and newer allow using a custom credential helper to inject credentials into remote file requests in a secure way without affecting caching. uv v0.9.16 and newer has built-in support for this protocol. Once uv is logged in to pyx, you can use the following .bazelrc to enable the credential helper for all pyx urls:
.bazelrc
common --credential_helper=*.astralhosted.com=%workspace%/bazel/uv-auth-helper
common --credential-helper=*.pyx.dev=%workspace%/bazel/uv-auth-helper
Where bazel/uv-auth-helper is a script that invokes uv auth helper with the right arguments:
bazel/uv-auth-helper
#!/usr/bin/env bash
exec uv auth helper --protocol=bazel "$@"

​
Authenticating with Dependabot

pyx can be configured as a private registry in GitHub’s Dependabot, allowing Dependabot to update dependencies from pyx. To configure Dependabot to use pyx, add the following to your .github/dependabot.yml: 
version: 2
updates:
  - package-ecosystem: "uv"
    directory: "/"
    registries:
      - pyx
      - files
    schedule:
      interval: "weekly"
registries:
  files:
    type: python-index
    url: "https://files.astralhosted.com"
    username: __token__
    password: ${{ secrets.PYX_API_KEY }}

  pyx:
    type: python-index
    url: "https://api.pyx.dev/simple/acme/main"
    username: __token__
    password: ${{ secrets.PYX_API_KEY }}
Replace acme/main with the appropriate pyx index for your organization (e.g., public/pypi, astral-sh/cu126, or your organization’s private index).
Both the pyx and files registries must be included. The pyx registry serves the package index, while the files registry serves the package files from the CDN.
Then, add your pyx API key as a repository secret named PYX_API_KEY in your GitHub repository settings under Settings > Secrets and variables > Actions.

​
Authenticating with Artifactory

pyx can be configured as an upstream (remote) repository in JFrog Artifactory, allowing Artifactory to proxy requests to pyx. To configure pyx as a remote repository in Artifactory, first create a read-only API key in the pyx dashboard (pyx-sk-...), then create a PyPI-compatible remote repository with the following settings. In the Basic tab:
SettingValue
URLhttps://files.astralhosted.com
User Name__token__
Password / Access Tokenpyx-sk-...
Enable Token Authentication✅
Registry URLhttps://api.pyx.dev
Registry Index Location Suffixsimple/acme/main
To ensure that Artifactory can access both the API (api.pyx.dev) and the CDN (files.astralhosted.com), set the following options in the Advanced tab:
SettingValue
Lenient Host Authentication✅
Bypass HEAD Requests✅
The remaining settings can be left at their default values.
If you’re configuring a pyx View as an upstream, set the URL to https://views.astralhosted.com instead of https://files.astralhosted.com. When using static IPs, use https://api-static.pyx.dev, https://files-static.astralhosted.com, or https://views-static.astralhosted.com accordingly.

​
Migrating off the uv alpha

Prior to v0.8.15, pyx support shipped in a separate, pyx-enabled alpha build of uv. If you’re migrating off the uv alpha (e.g., v0.8.12-alpha.3), note the following changes to the authentication interface:
  • uv auth login is now uv auth login pyx.dev
  • uv auth logout is now uv auth logout pyx.dev
  • uv auth token is now uv auth token pyx.dev
  • UV_API_KEY is now PYX_API_KEY (UV_API_KEY will continue to be supported temporarily for backwards-compatibility)
  • UV_AUTH_TOKEN is now PYX_AUTH_TOKEN (UV_AUTH_TOKEN will continue to be supported temporarily for backwards-compatibility)
If you’re already logged-in via the alpha build, you should remain logged-in when upgrading to uv v0.8.15.