Skip to content

Git credentials

uv allows packages to be installed from private Git repositories using SSH or HTTP authentication.

SSH authentication

To authenticate using an SSH key, use the ssh:// protocol:

SSH authentication requires using the username git.

See the GitHub SSH documentation for more details on how to configure SSH.

HTTP authentication

To authenticate over HTTP Basic authentication using a password or token:

  • git+https://<user>:<token>@<hostname>/... (e.g., git+https://git:[email protected]/astral-sh/uv)
  • git+https://<token>@<hostname>/... (e.g., git+https://[email protected]/astral-sh/uv)
  • git+https://<user>@<hostname>/... (e.g., git+https://[email protected]/astral-sh/uv)

Note

When using a GitHub personal access token, the username is arbitrary. GitHub doesn't allow you to use your account name and password in URLs like this, although other hosts may.

If there are no credentials present in the URL and authentication is needed, the Git credential helper will be queried.

Persistence of credentials

When using uv add, uv will not persist Git credentials to the pyproject.toml or uv.lock. These files are often included in source control and distributions, so it is generally unsafe to include credentials in them.

If you have a Git credential helper configured, your credentials may be automatically persisted, resulting in successful subsequent fetches of the dependency. However, if you do not have a Git credential helper or the project is used on a machine without credentials seeded, uv will fail to fetch the dependency.

You may force uv to persist Git credentials by passing the --raw option to uv add. However, we strongly recommend setting up a credential helper instead.

Git credential helpers

Git credential helpers are used to store and retrieve Git credentials. See the Git documentation to learn more.

If you're using GitHub, the simplest way to set up a credential helper is to install the gh CLI and use:

$ gh auth login

See the gh auth login documentation for more details.

Note

When using gh auth login interactively, the credential helper will be configured automatically. But when using gh auth login --with-token, as in the uv GitHub Actions guide, the gh auth setup-git command will need to be run afterwards to configure the credential helper.