Text of packaging.python.org › en › latest › discussions › downstream-packaging as Styx crawled it on Nov 18, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Supporting downstream packaging - Python Packaging User Guide

Skip to content Back to top View this page Edit this page Supporting downstream packaging ¶ Page Status : Draft Last Reviewed : 2025-? While PyPI and the Python packaging tools such as pip are the primary means of distributing Python packages, they are also often made available as part of other packaging ecosystems. These repackaging efforts are collectively called downstream packaging (your own efforts are called upstream packaging), and include such projects as Linux distributions, Conda, Homebrew and MacPorts.

They generally aim to provide improved support for use cases that cannot be handled via Python packaging tools alone, such as native integration with a specific operating system, or assured compatibility with specific versions of non-Python software. This discussion attempts to explain how downstream packaging is usually done, and what additional challenges downstream packagers typically face. It aims to provide some optional guidelines that project maintainers may choose to follow which help make downstream packaging significantly easier (without imposing any major maintenance hassles on the upstream project).

Note that this is not an all-or-nothing proposal — anything that upstream maintainers can do is useful, even if it’s only a small part. Downstream maintainers are also willing to prepare patches to resolve these issues. Having these patches merged can be very helpful, since it removes the need for different downstreams to carry and keep rebasing the same patches, and the risk of applying inconsistent solutions to the same problem.

Establishing a good relationship between software maintainers and downstream packagers can bring mutual benefits. Downstreams are often willing to share their experience, time and hardware to improve your package. They are sometimes in a better position to see how your package is used in practice, and to provide information about its relationships with other packages that would otherwise require significant effort to obtain.

Packagers can often find bugs before your users hit them in production, provide bug reports of good quality, and supply patches whenever they can. For example, they are regularly active in ensuring the packages they redistribute are updated for any compatibility issues that arise when a new Python version is released. Please note that downstream builds include not only binary redistribution, but also source builds done on user systems (in source-first distributions such as Gentoo Linux, for example).

Provide complete source distributions ¶ Why? ¶ The vast majority of downstream packagers prefer to build packages from source, rather than use the upstream-provided wheels. In some cases, using sources is actually required for the package to be included in the distribution. This is also true of pure Python packages that provide universal wheels. The reasons for using source distributions may include: Being able to audit the source code of all packages.

Being able to run the test suite and build documentation. Being able to easily apply patches, including backporting commits from the project’s repository and sending patches back to the project. Being able to build on a specific platform that is not covered by upstream builds. Being able to build against specific versions of system libraries. Having a consistent build process across all Python packages. While it is usually possible to build packages from a Git repository, there are a few important reasons to provide a static archive file instead: Fetching a single file is often more efficient, more reliable and better supported than e.g. using a Git clone.

This can help users with poor Internet connectivity. Downstreams often use hashes to verify the authenticity of source files on subsequent builds, which require that they remain bitwise identical over time. For example, automatically generated Git archives do not guarantee this, as the compressed data may change if gzip is upgraded on the server. Archive files can be mirrored, reducing both upstream and downstream bandwidth use.

The actual builds can afterwards be performed in firewalled or offline environments, that can only access source files provided by the local mirror or redistributed earlier. Explicitly publishing archive files can ensure that any dependencies on version control system metadata are resolved when creating the source archive. For example, automatically generated Git archives omit all of the commit tag information, potentially resulting in incorrect version details in the resulting builds.

How? ¶ Ideally, a source distribution archive published on PyPI should include all the files from the package’s Git repository that are necessary to build the package itself, run its test suite, build and install its documentation, and any other files that may be useful to end users, such as shell completions, editor support files, and so on. This point applies only to the files belonging to the package itself. The downstream packaging process, much like Python package managers, will provision the necessary Python dependencies, system tools and external libraries that are needed by your package and its build scripts.

However, the files listing these dependencies (for example, requirements*.txt files) should also be included, to help downstreams determine the needed dependencies, and check for changes in them. Some projects have concerns related to Python package managers using source distributions from PyPI. They do not wish to increase their size with files that are not used by these tools, or they do not wish to publish source distributions at all, as they enable a problematic or outright nonfunctional fallback to building the particular project from source.

In these cases, a good compromise may be to publish a separate source archive for downstream use elsewhere, for example by attaching it to a GitHub release. Alternatively, large files, such as test data, can be split into separate archives. On the other hand, some projects ( NumPy , for instance) decide to include tests in their installed packages. This has the added advantage of permitting users to run tests after installing them, for example to check for regressions after upgrading a dependency.

Yet another approach is to split tests or test data into a separate Python package. Such an approach was taken by the cryptography project, with the large test vectors being split to cryptography-vectors package. A good idea is to use your source distribution in the release workflow. For example, the build tool does exactly that — it first builds a source distribution, and then uses it to build a wheel. This ensures that the source distribution actually works, and that it won’t accidentally install fewer files than the official wheels.

Ideally, also use the source distribution to run tests, build documentation, and so on, or add specific tests to make sure that all necessary files were actually included. Understandably, this requires more effort, so it’s fine not do that — downstream packagers will report any missing files promptly. Do not use the Internet during the build process ¶ Why? ¶ Downstream builds are frequently done in sandboxed environments that cannot access the Internet.

The package sources are unpacked into this environment, and all the necessary dependencies are installed. Even if this is not the case, and assuming that you took sufficient care to properly authenticate downloads, using the Internet is discouraged for a number of reasons: The Internet connection may be unstable (e.g. due to poor reception) or suffer from temporary problems that could cause the process to fail or hang.

The remote resources may become temporarily or even permanently unavailable, making the build no longer possible. This is especially problematic when someone needs to build an old package version. The remote resources may change, making the build not reproducible. Accessing remote servers poses a privacy issue and a p

The rest of this page is on the live site.