English Japanese
Python Packaging Guidelines
This version of Python Packaging Guidelines is in effect since 2021 and represents a major rewrite and paradigm shift. Not all packages are updated to reflect this. Older guidelines are still being kept up to date, and existing packages *MAY* use them instead of this document:
xref:Python_201x.adoc[“201x-era” Python packaging guidelines] (Packages using these usually use the <<py3_install,`+%py3_install+`>> or <<py3_install_wheel,`+%py3_install_wheel+` macro>> or call `+setup.py install+`.)
xref:Python_Appendix.adoc#_python_2_packages[Python 2 appendix] Note that Python 2 packages require a FESCo exception.
These guidelines only support current Fedora releases. For older releases (such as in EPEL 8), consult the xref:Python_201x.adoc[201x-era guidelines].
The two <<Distro-wide guidelines>> below apply to all software in Fedora that uses Python at build- or run-time.
The rest of the Guidelines apply to packages that ship code that can be imported with Python’s `+import+` statement. Specifically, that is all packages that install files under `+/usr/lib*/python*/+`.
Except for the two “Distro-wide guidelines”, these Guidelines do not apply to simple one-file scripts or utilities, especially if these are included with software not written in Python. However, if an application (e.g. CLI tool, script or GUI app) needs a more complex Python library, the library *SHOULD* be packaged as an importable library under these guidelines.
A major goal for Python packaging in Fedora is to _harmonize with the wider Python ecosystem_, that is, the https://pypa.io[Python Packaging Authority] (PyPA) standards and the https://pypi.org/[Python Package Index] (PyPI). Packagers *SHOULD* be prepared to get involved with upstream projects to establish best practices as outlined here. We wish to improve both Fedora and the wider Python ecosystem.
Some build tools (like CMake or autotools) may not work with the latest PyPA standards yet. (For example, they might generate `+.egg-info+` directories rather than `+.dist-info+`.) While this document's normative points (MUST/SHOULD) are tool-agnostic, many of the practical tips and helper macros will not be applicable. If this affects you, consider contacting the https://lists.fedoraproject.org/archives/list/python-devel@lists.fedoraproject.org/[Python SIG] for guidance and/or following the xref:Python_201x.adoc[older guidelines] for the time being.
Fedora’s Python SIG not only develops these guidelines, but it’s also involved in PyPA standards and Python packaging best practices. Check out https://fedoraproject.org/wiki/SIGs/Python[the wiki] or https://lists.fedoraproject.org/archives/list/python-devel@lists.fedoraproject.org/[mailing list] if you need help or wish to help out.
Distro-wide guidelines
BuildRequire python3-devel
*Every* package that uses Python (at runtime and/or build time)
and/or installs Python modules
*MUST* explicitly include `+BuildRequires: python3-devel+`
in its `+.spec+` file,
even if Python is not actually invoked during build time.
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.
Mandatory macros
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.