Skip to content

Host Your Python Content

This section assumes that you have a repository with content in it. To do this, see the sync or upload documentation.

Make a Python Index (Create a Distribution)

To host your Python content as a PyPI compatible index, (which makes it consumable by pip), users create a distribution which will serve the content in the repository at ${BASE_ADDR}/pypi/${DIST_BASE_PATH}/.

# Distributions are created asynchronously. Create one, and specify the repository that will
# be served at the base path specified.
pulp python distribution create --name foo --base-path foo --repository foo

{
  "pulp_href": "/pulp/api/v3/distributions/python/pypi/0196ba32-0be6-7f85-bbb3-cf561a4e2d88/",
  "prn": "prn:python.pythondistribution:0196ba32-0be6-7f85-bbb3-cf561a4e2d88",
  "pulp_created": "2025-05-10T12:36:04.200189Z",
  "pulp_last_updated": "2025-05-10T12:36:04.200232Z",
  "base_path": "foo",
  "base_url": "http://localhost:5001/pypi/foo/",
  "content_guard": null,
  "no_content_change_since": "2025-05-10T12:36:04.200232Z",
  "hidden": false,
  "pulp_labels": {},
  "name": "foo",
  "repository": "/pulp/api/v3/repositories/python/python/019cf738-6951-7b25-b26f-182683dc32f2/",
  "repository_version": null,
  "publication": null,
  "allow_uploads": true,
  "remote": null
}

Setting the distribution's repository field will auto-serve the latest version of that repository. If you wish to only serve content from a specific version you can use the repository_version field.

Enable Pull-Through Caching

Only packages present in your repository will be available from your index, but adding a remote source to your distribution will enable the pull-through cache feature. This feature allows you to install any package from the remote source and have Pulp store that package in your repository.

# Add remote to distribution to enable pull-through caching
pulp python distribution update --name foo --remote bar

Note

Pull-through caching will respect the includes/excludes filters on the supplied remote.

Note

Setting the remote on a distribution without a repository will cause requested content to be saved as orphans.

Warning

Chaining pull-through indices, having a pull-through point to another pull-through, does not work.

Use the newly created distribution

The metadata and packages can now be retrieved from the distribution:

http "${BASE_ADDR}/pypi/foo/simple/"
http "${BASE_ADDR}/pypi/foo/simple/shelf-reader/"

Note

When domains are enabled, it is necessary to include the domain name within the URL, like so: ${BASE_ADDR}/pypi/${DOMAIN_NAME}/foo/simple/

The content is also pip installable:

pip install --trusted-host localhost -i "${BASE_ADDR}/pypi/foo/simple/" shelf-reader

If you don't want to specify the distribution path every time, you can modify your pip.conf file:

cat pip.conf

[global]
index-url = http://localhost:24817/pypi/foo/simple/

The above configuration informs pip to install from pulp:

pip install --trusted-host localhost shelf-reader

See the pip docs for more details.

Discover new packages with RSS feeds

Each index exposes PyPI-compatible RSS feeds so clients can learn about newly added projects and releases without polling the simple or JSON APIs. Items are grouped by project or by (name, version) release, not by individual wheel or sdist files. Timestamps reflect when the package was added to this index, not when the content unit was first stored in Pulp.

http "${BASE_ADDR}/pypi/foo/rss/updates.xml"
http "${BASE_ADDR}/pypi/foo/rss/packages.xml"
http "${BASE_ADDR}/pypi/foo/rss/project/shelf-reader/releases.xml"
  • rss/updates.xml lists the latest releases added to the index (up to 100).
  • rss/packages.xml lists projects that are new to the index (up to 40). Adding another version of an existing project does not create a new packages entry.
  • rss/project/<name>/releases.xml lists the latest releases of one project (up to 40). A missing project returns 404.

Pull-through packages appear in the feeds only after they have been stored in the repository. Item links point at the existing JSON metadata URLs for that project or release.

Migrating off Publications

Ever since the release of pulp-python 3.4, publications have no longer been required to serve content to Python compatible tooling. Publications became deprecated in version 3.27, but it is recommended to move off of them even on early versions as many new features like pull-through caching, simple JSON, attestations, were not built to work with publications. To move off publications follow these three steps:

  1. Switch any distribution serving a publication to a repository or repository-version
  2. Set autopublish=False for all repositories
  3. Delete all python publications

Warning

Publications may be removed in a future pulp-python version.

Note

To maintain backwards compatibility, /pypi/ endpoints will always try to use a publication if there is one available for the repository. We recommend deleting every publication for a repository if you wish to use the newer features.