Keep credentials out of files you commit. Pip supports three routes: credentials in the index URL, a netrc file, and the keyring library. The URL route is simplest and the easiest to leak, because the secret ends up in config, logs and shell history. Netrc or keyring keep it in a separate, permissioned place.
The three routes in pip
The pip authentication guide documents each.
URL credentials. Put a username and password, or a single token as the username, in the index URL. Special characters must be percent encoded.
netrc. If the URL carries no credentials, pip looks up the host in the user's netrc file. The guide notes the file is ASCII only.
keyring. Pip can read credentials stored in the keyring library, enabled with the keyring provider option, whose values are auto, disabled, import and subprocess.
| Route | Where the secret lives | Leak risk |
|---|---|---|
| In the URL | Config, env, command history | High |
| netrc | A file in the home directory | Medium, needs strict permissions |
| keyring | The operating system store | Lower, but harder in CI |
Where URL credentials leak
A token in an index URL can end up in many places, even if you never commit the URL on purpose.
- A requirements file that begins with an index line.
- A pip.conf checked into a repository.
- Build logs that echo the command or environment.
- A Dockerfile layer that sets the variable, which then persists in image history.
- Shell history on a build host.
If you find a token in any of those, treat it as exposed. Rotate it, then remove it. For leaked registry tokens, see leaked registry token: what to check on npm and PyPI.
A safer pattern for CI
Use the credential store your CI system already provides, and inject the secret only for the step that installs.
- Store the token as a masked secret in CI.
- Create a netrc file at job start from that secret, with permissions limited to the build user, and delete it at job end.
- Leave the index URL without credentials in committed config.
- Use a token with read only access to the index, scoped to the packages the job needs.
For a developer machine, the keyring route is a good fit. The guide shows the provider options and a way to set them in config, which keeps passwords out of the command line.
A warning from the guide
The auto provider does not query keyring when pip is run with no-input, because the keyring might prompt. Tools that call pip for you often pass that flag. The guide notes you can force keyring use by choosing the import or subprocess provider, but warns this can make tools such as pipx and Pipenv appear to hang if the keyring waits for input. Test in a non-interactive job before relying on it.
Checklist
- No credentials in any committed file.
- Read only tokens for installs.
- Tokens rotated on a schedule and after any exposure.
- Logs checked for the index host name followed by an at sign.
Use your source host's own features or a dedicated tool for that last check. Safeguard's dependency scanning covers what the install brought in. A free scan is available at gold.safeguard.sh/scan.
Quick check
Can I pass a token with no username?
For indexes that need only a single token, the guide says to provide the token as the username and no password.
Is netrc safer than the URL?
Usually, because the secret leaves your config and command history, but the file still needs tight permissions.
Sources
Last reviewed: 19 October 2026.
