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: ...

​
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.