Python Packaging Guidelines

Every package that uses Python (at run-time and/or build-time) and/or installs Python modules MUST have a build-time dependency on python3-devel, even if Python is not actually invoked during build-time. Such a package MUST use one of the following in its .spec file:

Only having a transitive build-time dependency on python3-devel is not sufficient. If the package uses an alternate Python interpreter instead of python3 (e.g. pypy, jython, python2.7), it MAY instead require the corresponding *-devel package.

The *-devel package brings in relevant RPM macros. It may also enable automated or manual checks: for example, Python maintainers use this requirement to list packages that use Python in some way and might be affected by planned changes.

The following macros MUST be used where applicable.

The expansions in parentheses are provided only as reference/examples.

The macros are defined for you in all supported Fedora and EPEL versions.

The rest of this document uses these macros, along with %{_bindir} (/usr/bin/), instead of the raw path names.

Fedora primarily targets CPython, the reference implementation of the Python language. We generally use “Python” to mean CPython.

Alternate implementations like pypy are available, but currently lack comprehensive tooling and guidelines for packaging. When targetting these, there are no hard rules (except the general Fedora packaging guidelines). But please try to abide by the spirit of these guidelines. When in doubt, consider consulting the Python SIG.

Fedora packages MUST NOT depend on other versions of the CPython interpreter than the current python3.

In Fedora, Python libraries are packaged for a single version of Python, called python3. For example, in Fedora 32, python3 is Python 3.8.

In the past, there were multiple Python stacks, e.g. python3.7 and python2.7, installable together on the same machine. That is also the case in some projects that build on top of Fedora, like RHEL, EPEL and CentOS. Fedora might re-introduce parallell-installable stacks in the future (for example if a switch to a new Python version needs a transition period, or if enough interested maintainers somehow appear).

Fedora does include alternate interpreter versions, e.g. python2.7 or python3.5, but these are meant only for developers that need to test upstream code. Bug and security fixes for these interpreters only cover this use case. Packages such as pip or tox, which enable setting up isolated environments and installing third-party packages into them, MAY, as an exception to the rule above, use these interpreters as long as this is coordinated with the maintainers of the relevant Python interpreter.

Most of these names are case-sensitive machine-friendly identifiers, but the project name has human-friendly semantics: it is case-insensitive and treats some sets of characters (like ._-) specially. For automated use, it needs to be normalized to a canonical format used by Python tools and services such as setuptools, pip and PyPI. For example, the canonical name of the Django project is django (in lowercase). This normalization is defined in PEP 503, and the %{py_dist_name} macro implements it for Fedora packaging. The canonical name is obtained by switching the project name to lower case and converting all runs of non-alphanumeric characters to single “-” characters. Example: “The $$$ Tree” becomes “the-tree”.

Elsewhere in this text, the metavariable DISTNAME refers to the canonical form of the project name.

Note that in some places, the original, non-normalized project name must be used. For example, the %pypi_source macro and the %autosetup macro need Django, not django.

The character + in names of built (i.e. non-SRPM) packages that include .dist-info or .egg-info directories is reserved for Extras and MUST NOT be used for any other purpose.

As an exception, + characters MAY appear at the end of such names.

The + character triggers the automatic dependency generator for extras.

Replace any + signs in the upstream name with -. Omit + signs on the beginning of the name. Consider adding Provides for the original name with + characters to make the package easier to find for users.

A built (i.e. non-SRPM) package for a Python library MUST be named with the prefix python3-. A source package containing primarily a Python library MUST be named with the prefix python-.

The Fedora package’s name SHOULD contain the Canonical project name. If possible, the project name SHOULD be the same as the name of the main importable module, in lowercase, with underscores (_) replaced by dashes (-).

If the importable module name and the project name do not match, users frequently end up confused. In this case, packagers SHOULD ensure that upstream is aware of the problem and (especially for new packages where renaming is feasible) strive to get the package renamed. The Python SIG is available for assistance.

A Python library is a package meant to be imported in Python, such as with import requests. Tools like Ansible or IDLE, whose code is importable but not primarily meant to be imported from other software, are not considered libraries in this sense. So, this section does not apply for them. (See the general Libraries and Applications guidelines for general guidance.)

The Fedora component (source package) name for a library should be formed by taking the canonical project name and prepending python- if it does not already start with python-. This may leads to conflicts (e.g. between bugzilla and python-bugzilla). In that case, ensure upstream is aware of the potentially confusing naming and apply best judgment.

Packages that primarily provide applications, services or any kind of executables SHOULD be named according to the general Fedora naming guidelines (e.g. ansible).

Consider adding a virtual provide according to Library naming above (e.g. python3-PROJECTNAME), if it would help users find the package.

Packages MUST include the source file (*.py) AND the bytecode cache (*.pyc) for each pure-Python importable module. The source files MUST be included in the same package as the bytecode cache.

Scripts that are not importable (typically ones in %{_bindir} or %{_libexecdir}) SHOULD NOT be byte-compiled.

The cache files are found in a __pycache__ directory and have an interpreter-dependent suffix like .cpython-39.pyc.

The cache is not necessary to run the software, but if it is not found, Python will try to create it when a module is imported. If this succeeds, the file is not tracked by RPM and it will linger on the system after uninstallation. If it does not succeed, users can get spurious SELinux AVC denials in the logs.

Normally, byte compilation (generating the cache files) is done for you by the brp-python-bytecompile BRP script, which runs automatically after the %install section of the spec file has been processed. It byte-compiles any .py files that it finds in %{python3_sitelib} or %{python3_sitearch}.

You must include these files of your package (i.e. in the %files section).

If the code is in a subdirectory (importable package), include the entire directory:

Adding the trailing slash is best practice for directories.

However, this cannot be used for top-level modules (those directly in e.g. %{python3_sitelib}), because both %{python3_sitelib} and %{python3_sitelib}/__pycache__/ are owned by Python itself. Here, the %pycached macro can help. It expands to the given *.py source file and its corresponding cache file(s). For example:

expands roughly to:

Each Python package MUST include Package Distribution Metadata conforming to PyPA specifications (specifically, Recording installed projects).

The metadata SHOULD be included in the same subpackage as the main importable module, if there is one.

This applies to libraries (e.g. python-requests) as well as tools (e.g. ansible).

When software is split into several subpackages, it is OK to only ship metadata in one built RPM. In this case, consider working with upstream to also split the upstream project.

The metadata takes the form of a .dist-info directory installed in %{python3_sitelib} or %{python3_sitearch}, and contains information that tools like importlib.metadata use to introspect installed libraries.

For example, a project named MyLib with importable package mylib could be packaged with:

Note that some older tools instead put metadata in an .egg-info directory, or even a single file. This won’t happen if you use the %pyproject_wheel macro. If your package uses a build system that generates an .egg-info directory or file, please contact Python SIG.

As an exception, the Python standard library MAY ship without this metadata.

Packages MUST NOT own shared directories owned by Python itself, such as the top-level __pycache__ directories (%{python3_sitelib}/__pycache__, %{python3_sitearch}/__pycache__).

Similarly to the general rule, packagers SHOULD NOT simply glob everything under a shared directory.

In addition to the general list, the following SHOULD NOT be used in %files:

This rule serves as a check against common mistakes which are otherwise hard to detect. It does limit some possibilities for automation.

The most common mistakes this rule prevents are:

For any module intended to be used in Python 3 with import MODNAME, the package that includes it SHOULD provide python3-MODNAME, with underscores (_) replaced by dashes (-).

This is of course always the case if the package is named python3-MODNAME. If the subpackage has some other name, then add %py_provides python3-MODNAME explicitly. See the following section to learn about %py_provides.

For any FOO, a package that provides python3-FOO SHOULD use %py_provides or an automatic generator to also provide python-FOO and python3.X-FOO, where X is the minor version of the interpreter.

The provide SHOULD NOT be added manually: if a generator or macro is not used, do not add the python-FOO / python3.X-FOO provides at all.

This is done automatically for package names by a generator. If absolutely necessary, the generator can be disabled by undefining the %__pythonname_provides macro.

For provides that aren’t package names, or (for technical reasons) for packages without files, the generator will not work. For these cases, the following invocation will provide python3-FOO, python-FOO and python3.X-FOO:

Using the generator or macro is important, because the specific form of the provide may change in the future.

Every Python package MUST provide python3dist(DISTNAME) and python3.Xdist(DISTNAME), where X is the minor version of the interpreter and DISTNAME is the Canonical project name corresponding to the Dist-info metadata. For example, python3-django would provide python3dist(django) and python3.9dist(django).

This is generated automatically from the dist-info metadata. The provide SHOULD NOT be added manually: if the generator fails to add it, the metadata MUST be fixed.

These Provides are used for automatically generated Requires.

If absolutely necessary, the automatic generator can be disabled by undefining the %{?__pythondist_provides} macro. Consider discussing your use case with the Python SIG if you need to do this.

As mentioned above, each Python package MUST explicitly BuildRequire python3-devel.

Packages MUST NOT have dependencies (either build-time or runtime) with the unversioned prefix python- if the corresponding python3- dependency can be used instead.

Packages SHOULD NOT have explicit dependencies (either build-time or runtime) with a minor-version prefix such as python3.8- or python3.8dist(. Such dependencies SHOULD instead be automatically generated or a macro should be used to get the version.

Packages SHOULD NOT have an explicit runtime dependency on python3.

Instead of depending on python3, packages have an automatic dependency on python(abi) = 3.X when they install files to %{python3_sitelib} or %{python3_sitearch}, or they have an automatic dependency on /usr/bin/python3 if they have executable Python scripts, or they have an automatic dependency on libpython3.X.so.1.0() if they embed Python.

These rules help ensure a smooth upgrade path when python3 is updated in new versions of Fedora.

Packages MUST use the automatic Python run-time dependency generator.

Packages SHOULD use the opt-in build-dependency generator if possible.

The packager MUST inspect the generated requires for correctness. All dependencies MUST be resolvable within the targeted Fedora version.

Any necessary changes MUST be done by patches or modifying the source (e.g. with sed), rather than disabling the generator. The resulting change SHOULD be offered to upstream. As an exception, filtering MAY be used for temporary workarounds and bootstrapping.

Dependencies covered by the generators SHOULD NOT be repeated in the .spec file. (For example, if the generator finds a requests dependency, then Requires: python3-requests is redundant.)

The automatically generated requirements are in the form python3.Xdist(DISTNAME), potentially augmented with version requirements or combined together with rich dependencies. Any .0 suffixes are removed from version numbers to match the behavior of Python tools. (PEP 440 specifies that X.Y and X.Y.0 are treated as equal.)

Note that the generators only cover Python packages. Other dependencies, often C libraries like openssl-devel, must be specified in the .spec file manually.

Where the requirements are specified in the source depends on each project’s build system and preferences. Common locations are pyproject.toml, setup.py, setup.cfg, config.toml.

See the Tests section.

Python extras are a way for Python projects to declare that extra dependencies are required for additional functionality.

For example, requests has several standard dependencies (e.g. urllib3). But it also declares an extra named requests[security], which lists additional dependencies (e.g. cryptography). Unlike RPM subpackages, extras can only specify additional dependencies, not additional files. The main package will work if the optional dependency is not installed, but it might have limited functionality.

Python tools treat extras as virtual packages. For example, if a user runs pip install 'requests[security]', or installs a project that depends on requests[security], both requests and cryptography will be installed.

In Fedora, extras are usually provided by packages with no files. Instead of square brackets, Fedora package names conventionally use the + character (which is valid in RPM package names, but not in Python canonical project names nor in extras identifiers).

Shebang lines to invoke Python MUST use %{python3} as the interpreter.

Shebang lines to invoke Python SHOULD be #!%{python3} -%{py3_shebang_flags} and they MAY include extra flags.

If (some of) the default flags from the %{py3_shebang_flags} macro are not desirable, packages SHOULD explicitly redefine the macro to remove them by undefining the relevant %{_py3_shebang_...} macro.

Using #!%{python3} (#!/usr/bin/python3) rather than e.g. #!/usr/bin/env python ensures that the system-wide Python interpreter is used to run the code, even if the user modifies $PATH (e.g. by activating a virtual environment).

By default, -%{py3_shebang_flags} expands to -sP (or just -s on Python version lower than 3.11 and Fedora Linux older than 37).

The -s flag, stored in the %{_py3_shebang_s} macro, means don’t add user site directory to sys.path. That ensures the user’s Python packages (e.g. installed by pip install --user, or just placed in the current directory) don’t interfere with the RPM installed software. Sometimes, such content is desirable, such as with plugins.

The -P flag, stored in the %{_py3_shebang_P} macro, means don’t add the script’s directory to sys.path. Sometimes, adding the script’s directory to sys.path is desirable, such as with executable Python scripts installed in a custom directory, importing each other.

Removing the undesired flag(s) from the %{py3_shebang_flags} macro rather than not using the macro at all, ensures that existing or future automation won’t add the flag.

The %pyproject_install macro automatically changes all Python shebangs in %{buildroot}%{_bindir}/* to use %{python3} and add contents of the %{py3_shebang_flags} macro to the existing flags. If you’re not using that macro or you need to change a shebang in a different directory, you can use the %py3_shebang_fix macro as follows:

Every executable TOOL for which the current version of Python matters SHOULD also be invokable by python3 -m TOOL.

If the software doesn’t provide this functionality, packagers SHOULD ask the upstream to add it.

This applies to tools that modify the current Python environment (like installing or querying packages), use Python for configuration, or use Python to run plugins. It does not apply to tools like GIMP or Bash which support plugins in multiple languages and/or have other means to specify the interpreter.

For example, pip can be invoked as python3 -m pip.

This allows users to accurately specify the Python version used to run the software. This convention works across different environments that might not always set $PATH or install scripts consistently.

If a test suite exists upstream, it SHOULD be run in the %check section. If that is not possible with reasonable effort, at least a basic smoke test (such as importing the packaged module) MUST be run in %check.

You MAY exclude specific failing tests. You MUST NOT disable the entire testsuite or ignore its result to solve a build failure.

As an exception, you MAY disable tests with an appropriate %if conditional (e.g. bcond) when bootstrapping.

Most errors in Python happen at run-time, so tests are extremely important to root out issues, especially when mass rebuilds are required.

Common reasons for skipping tests in %check include requiring network access, dependencies not packaged in Fedora, and/or specialized hardware or resources.

In these cases, you can use the %pyproject_check_import or the %py3_check_import macro to test that installed modules are importable.

One part of the Python packaging ecosystem that is still not standardized is specifying test dependencies (and development dependencies in general).

A good, common way for upstreams to specify test dependencies is using an extra like [test], [testing] or [dev]. In this case, upstream’s instructions to install test dependencies might look like $ pip install -e.[test].

Projects using tox usually specify test dependencies in a tox-specific format: a requires key in the configuration.

These two forms are handled by the %pyproject_buildrequires macro.

If upstream does not use either form, list test dependencies as manual BuildRequires in the spec file, for example:

If you need to do this, consider asking upstream to add a [test] extra.

In %check, packages SHOULD NOT run “linters”: code style checkers, test coverage checkers and other tools that check code quality rather than functionality.

Tools like black, pylint, flake8, or mypy are often “opinionated” and their “opinions” change frequently enough that they are nuisance in Fedora, where the linter is not pinned to an exact version. Furthermore, some of these tools take a long time to adapt to new Python versions, preventing early testing with Alpha and Beta releases of Python. And they are just not needed: wrongly formatted code is not important enough for the Fedora packager to bug the upstream about it. Making such an issue break a package build is entirely unreasonable.

Linters do make sense in upstream CI. But not in Fedora.

If a linter is used, disable it and remove the dependency on it. If that is not easy, talk to upstream about making it easy (for example with a configuration option or a separate tox environment).

For packages that contain such linters, use them at runtime or extend them, you will usually need to run the linter in %check. Run it to test functionality, not code quality of the packaged software.

The “pyproject macros” are most useful for packaging Python projects that use the pyproject.toml file defined in PEP 518 and PEP 517, which specifies the package’s build dependencies (including the build system, such as setuptools, flit or poetry).

If pyproject.toml is not found, the macros automatically fall backs to using setuptools with configuration in setup.cfg/setup.py.

A full tutorial and discussion for the macros is available in the macros’ README.

The following macros are available for cases where automatic generation is turned off. They can also be useful for handling files in non-standard locations where the generators don’t look.

The following macros can be redefined for special use cases.

When comparing Python versions (e.g. to ask: is %{python3_version} greater than 3.8?), using naïve %if %{python3_version} > 3.8 or %if "%{python3_version}" > "3.8" is not possible, because the comparison is performed alphabetically on strings. Hence it is true that "3.10" < "3.8" (which is not desired).

It is possible to explicitly compare version literals by using the v prefix, similar to the Python string prefixes:

The following macros can turn off Python-specific automation.

Consider contacting the Python SIG if you need to do this.

The following macros are deprecated. See the 201x-era Python Packaging guidelines for how some of them were used.