Skip to content

Install Python packages from CloudRepo

View as Markdown

pip reads CloudRepo like any other Python package index: give it the repository’s index URL, with the token in it, and install. This page is for the person whose project installs from a repository. To upload packages there, see Publish Python packages.

You need a Python repository and a repository token that reaches it. If you have neither yet: create a repository and create a token. A token that is Read only is enough to install.

Point pip at the repository

Section titled “Point pip at the repository”

pip takes the credential inside the index URL. The username is the email address of the account that created the token, with the @ written as %40, and the password is the token. On Windows the file is pip.ini.

~/.config/pip/pip.conf
[global]
index-url = https://you%40example.com:YOUR_REPOSITORY_TOKEN@your-org.mycloudrepo.io/repositories/your-repo/simple/

The index URL is https://<organization>.mycloudrepo.io/repositories/<repository>/simple/: your organization’s name, then the repository’s name as the admin portal shows it. Without /simple/ the URL answers the same index.

This file makes CloudRepo pip’s default index for every install. If a project installs public packages too, do not set index-url globally: use the three-step install below, which names CloudRepo only where it is needed.

To use the index for one command or one shell, or in CI, set PIP_INDEX_URL from your secret store instead of writing a file, and do not pass the URL on the command line:

Terminal
export PIP_INDEX_URL="https://you%40example.com:${CLOUDREPO_TOKEN}@your-org.mycloudrepo.io/repositories/your-repo/simple/"
pip install my-package

Expected: pip downloads my-package from your-org.mycloudrepo.io and prints Successfully installed.

Install private and public packages together

Section titled “Install private and public packages together”

Install your private packages from CloudRepo alone. Anyone can publish a package on PyPI under your private package’s name, and an install that can read PyPI as well may install theirs instead.

These steps assume pip’s default index is PyPI, so they do not use the index-url in the pip.conf above, or PIP_INDEX_URL in your shell. Step 2’s requirements file names CloudRepo itself. With a global index-url, step 1 would read CloudRepo instead of PyPI, and a hosted repository holds no public package.

pip cannot tie a package to an index. Given a second index (--extra-index-url, the extra-index-url key in pip.conf, or PIP_EXTRA_INDEX_URL), pip reads both as one and installs the highest version it finds in either, and an exact == pin does not help when both indexes have that version. So install in three steps, with one index each:

Terminal
# 1. Public packages, from PyPI (pip's default index)
pip install -r requirements.txt


# 2. Private packages, from CloudRepo and nothing else
pip install -r requirements-private.txt


# 3. Your own project, last, without its dependencies (steps 1 and 2 installed them)
pip install --no-deps -e .
requirements-private.txt
--index-url https://${CLOUDREPO_USERNAME}:${CLOUDREPO_TOKEN}@your-org.mycloudrepo.io/repositories/your-repo/simple/
acme-ml-core==3.2.1
acme-feature-pipeline==2.0.0
  • The --index-url line makes CloudRepo the only index for that command. Use the repository that hosts your private packages, not one that proxies PyPI. pip fills in ${CLOUDREPO_USERNAME} and ${CLOUDREPO_TOKEN} from the environment, so the file holds no credential and is safe to commit. CLOUDREPO_USERNAME is your plain email address.
  • Nothing step 1 installs may depend on a private package, your own project included: pip would fetch that private package from PyPI in step 1. Keep private package names, and . or -e ., out of requirements.txt.
  • Step 3 builds your project in an isolated environment that pip fills from PyPI. If [build-system] requires names a private package, put it in requirements-private.txt, put the public build requirements (such as setuptools) in requirements.txt, and run step 3 as pip install --no-deps --no-build-isolation -e ..
  • List the public packages that your private packages depend on in requirements.txt. Step 2 then finds them installed. If one is missing, step 2 fails rather than looking for it on PyPI.

Hashes protect something else. With pip install --require-hashes -r requirements.txt, pip installs only files whose SHA-256 you recorded, so a file published later under the same name and version is refused, whichever index serves it. Hashes do not choose the index: with two indexes the install can stop with a hash error instead of installing your copy. Record them from an install that read CloudRepo alone for your private packages, because a hash taken from PyPI’s copy protects PyPI’s copy.

When pip answers 401, 403 or 404

Section titled “When pip answers 401, 403 or 404”

pip prints the status it received, or No matching distribution found for a package it cannot find. Check these in order:

  • 401 Unauthorized. The credential was refused. The username must be the email address of the account that created the token, with the @ written as %40 (pip also accepts a bare @). __token__ is refused: that is the convention on pypi.org, and CloudRepo does not use it. The password must be the token itself, and a token that is expired or revoked fails the same way: the Repository Tokens page in the admin portal shows its status.
  • 403 Forbidden. The token does not reach this repository. A token reaches only the repositories ticked when it was created, so use one that includes it.
  • 404 Not Found, or no matching distribution. The repository does not hold that name and version, or the index URL is wrong. Check the organization and repository names in it. A proxy repository that the token does not reach also answers 404, not 403.

More: Repository tokens, for every client’s credential; Proxy repositories, to install public packages through CloudRepo; Python repositories, for uploading, overwrite protection and the other settings.