At any given time, the binary package python will represent the current default Debian Python version. The binary package python3 will represent the current Debian Python 3 version. As far as is reasonable, python and python3 should be treated as separate runtime systems with minimal interdependencies. In some cases, Python policy explicitly references Python helper programs such as python-support and python-central. None of these references apply to Python 3. It is a design goal to fully specify required interfaces and functions in policy for Python 3 and to avoid enshrining specific implmentation details in policy. Except as noted, policy for Python 3 is the same as Python with the addition of the version number as needed to distinguish them.

The default Debian Python version should always be the latest stable upstream release that can be fully integrated in the distribution. There may be newer supported or unsupported versions included in the distribution if they are not fully integrated for a particular release.

Apart from the default version, legacy versions of Python or beta versions of future releases may be included as well in the distribution, as long as they are needed by other packages, or as long as it seems reasonable to provide them. (Note: For the scope of this document, Python versions are synonymous to feature releases, i.e. Python 2.5 and 2.5.1 are sub-minor versions of the same Python version 2.5, but Python 2.4 and 2.5 are indeed different versions.)

For any version, the main binary package must be called pythonX.Y.

The set of currently supported python versions can be found in /usr/share/python/debian_defaults. This file is in Python ConfigParser format and defines four variables in its DEFAULT section: default-version which is the current default Python runtime, supported-versions which is the set of runtimes currently supported and for which modules should be built and byte-compiled, old-versions which is the list of runtimes which might still be on the system but for which should not be built anymore, and unsupported-versions which is the list of runtimes which should not be supported at all, that is modules should not be built or byte-compiled for these. The supported interface to this file is /usr/bin/pyversions. The Python 3 interface is through /usr/bin/py3versions.

unsupported-versions is a superset of (includes) old-versions and the default-version is always in supported-versions.

Newer versions might also appear in unsupported-versions before being moved to supported-versions.

For every Python version provided in the distribution, the binary package pythonX.Y shall provide a complete distribution for deployment of Python scripts and applications. The package must ensure that the binary /usr/bin/pythonX.Y is provided.

Installation of pythonX.Y shall provide the modules of the upstream Python distribution with some exceptions.

Excluded are modules that cannot be included for licensing reasons (for example the profile module), for dependency tracking purposes (for example the GPL-licensed gdbm module) or that should not be included for packaging reasons (for example the tk module which depends on Xorg). Some tools and files for the development of Python modules are split off in a separate binary package pythonX.Y-dev. Documentation will be provided separately as well.

At any time, the python binary package must ensure that /usr/bin/python is provided as a symlink to the current pythonX.Y executable. The python binary package must also depend on the appropriate pythonX.Y to ensure this runtime is installed.

The version of the python binary package must be greater than or equal to X.Y and smaller than X.Y+1.

For every Python version provided in the distribution, the binary package pythonX.Y-minimal might exist and should not be depended upon by other packages except the Python runtime packages themselves.

By default, Python modules are searched in the directories listed in the PYTHONPATH environment variable and in the sys.path Python variable. Since python2.4 version 2.4.5-3, python2.5 version 2.5.2-7, and python2.6 version 2.6.2-1 sys.path does not include a /usr/lib/pythonXY.zip entry anymore. Directories with private Python modules must be absent from the sys.path. Public Python modules not handled by python-central or python-support must be installed in the system Python modules directory, /usr/lib/pythonX.Y/dist-packages for python2.6 and later, and /usr/lib/pythonX.Y/site-packages for python2.5 and earlier. As an exception to the above, modules managed by python-support are installed in another directory which is added to the sys.path using the .pth mechanism. The .pth mechanism is documented in the Python documentation of the site module. A special directory is dedicated to public Python modules installed by the local administrator, /usr/local/lib/pythonX.Y/dist-packages for python2.6 and later, and /usr/local/lib/pythonX.Y/site-packages for python2.5 and earlier. For a local installation by the administrator of python2.6 and later, a special directory is reserved to Python modules which should only be available to this Python, /usr/local/lib/pythonX.Y/site-packages. Unfortunately, for python2.5 and earlier this directory is also visible to the system Python. Additional information on appending site-specific paths to the module search path is available in the official documentation of the site module.

When binary packages ship identical source code for multiple Python versions, for instance /usr/lib/python2.6/dist-packages/foo.py and /usr/lib/python2.5/site-packages/foo.py, these should point to a common file. A common location to share, across Python versions, arch-independent files which would otherwise go to the directory of system public modules is /usr/share/pyshared.

The python binary package has special hooks to allow other packages to act upon updates to the installed runtimes. This mechanism is required to handle changes of the default Python runtime in some packages and to enable the Python packaging helpers. There are three supported hook types which come in the form of scripts which are invoked from the maintainer scripts of the Python runtime packages when specific installations, removals, or upgrades occur.

/usr/share/python/runtime.d/*.rtinstall: these are called when a runtime is installed or becomes supported. The first argument is "rtinstall", the second argument is the affected runtime (for example pythonX.Y) and the third and fourth argument are the old and new version of this packaged runtime if this runtime was already installed but unsupported.

Python documentation is split out in separate binary packages pythonX.Y-doc. The binary package python-doc will always provide the documentation for the default Debian Python version.

TODO: Policy for documentation of third party packages.

Public modules used by other packages must have their binary package name prefixed with python-. It is recommended to use this prefix for all packages with public modules as they may be used by other packages in the future. Python 3 modules must be in a separate binary package prefixed with python3- to preserve run time separation between python and python3. The binary package for module foo should preferably be named python-foo, if the module name allows, but this is not required if the binary package ships multiple modules. In the latter case the maintainer chooses the name of the module which represents the package the most. Such a package should support the current Debian Python version, and more if possible (there are several tools to help implement this, see ). For example, if Python 2.3, 2.4, and 2.5 are supported, the Python statement import foo should import the module when the user is running any of /usr/bin/python2.3, /usr/bin/python2.4, and /usr/bin/python2.5. This requirement also applies to extension modules; binaries for all the supported Python versions should be included in a single package.

The optional X-Python-Version (preferred) or XS-Python-Version field in the general paragraph (the first one, for the source package) of debian/control specifies the versions of Python (not versions of Python 3) supported by the source package. Similarly, X-Python3-Version is used to specify the versions of Python 3 supported by the package. When not specified, they default to all currently supported Python (or Python 3) versions. They are used by some packaging scripts to automatically generate appropriate Depends and Provides lines. The format of the field may be one of the following: XS-Python-Version: >= X.Y XS-Python-Version: >= A.B, << X.Y XS-Python-Version: A.B, X.Y XS-Python-Version: all The keyword "all" means that the package supports any Python version available but might be deprecated in the future since using version numbers is clearer than "all" and encodes more information. The keyword "all" is limited to Python versions and must be ignored for Python 3 versions. Lists of multiple individual versions (e.g. 2.4, 2.5, 2.6) work for XS-Python-Version and will continue to be supported, but are not recommended and will not be supported by X-Python-Version or X-Python3-Version after the Squeeze release. The keyword "current" has been deprecated and used to mean that the package would only have to support a single version (even across default version changes). It must be ignored for Python 3 versions. Python 3 versions should never have been used in XS-Python-Version and should be considered deprecated at best. X-Python3-Version should be used instead.

The binary package paragraphs of your debian/control file should also have a line: XB-Python-Version: ${python:Versions} The python:Versions is substituted by the supported Python versions of the binary package, based on XS-Python-Version. (If you are not using python-central or python-support, you will need to handle this substitution yourself.) The format of the field XB-Python-Version is the same as the XS-Python-Version field for packages not containing extensions. Packages with extensions must list the versions explicitly.

If your package is used by another module or application that requires a specific Python version, it should also Provide: pythonX.Y-foo for each version it supports.

Packaged modules available for the default Python version (or many versions including the default) as described in must depend on "python (>= X.Y)". If they require other modules to work, they must depend on the corresponding python-foo. They must not depend on any pythonX.Y-foo.

Packaged modules available for one particular version of Python must depend on the corresponding pythonX.Y package instead. If they need other modules, they must depend on the corresponding pythonX.Y-foo packages, and must not depend on any python-foo.

Provides in binary packages of the form python-foo must be specified, if the package contains an extension for more than one python version. Provides should also be added on request of maintainers who depend on a non-default python version.

If a binary package provides any binary-independent modules (foo.py files), the corresponding byte-compiled modules (foo.pyc files) and optimized modules (foo.pyo files) must not ship in the package. Instead, they should be generated in the package's postinst, and removed in the package's prerm. The package's prerm has to make sure that both foo.pyc and foo.pyo are removed.

A binary package should only byte-compile the files which belong to the package.

The file /etc/python/debian_config allows configuration how modules should be byte-compiled. The postinst scripts should respect these settings.

Pure Python modules in private installation directories that are byte-compiled with the default Python version must be forcefully byte-compiled again when the default Python version changes. Public Python extensions should be bin-NMUed. Private Python extensions should be subject to binary NMUs every time the default interpreter changes, unless the extension is updated through a .rtupdate script.

Programs that can run with any version of Python must begin with #!/usr/bin/python or #!/usr/bin/env python (the former is preferred). They must also specify a dependency on python, with a versioned dependency if necessary.

If the program needs the python module foo, it must depend on the real package providing this module, usually python-foo but this name might vary when the package ships multiple modules.

A program which requires a specific version of Python must begin with #!/usr/bin/pythonX.Y (or #!/usr/bin/env pythonX.Y). It must also specify a dependency on pythonX.Y and on any pythonX.Y-foo package providing necessary modules. It should not depend on any python-foo package, unless it requires a specific version of the package (since virtual packages cannot be versioned). If this is the case, it should depend on both the virtual package and the main package (e.g. Depends: python2.4-foo, python-foo (>= 1.0)).

The notes on installation directories and byte-compilation for programs that support any version of Python also apply to programs supporting only a single Python version. Modules to be byte-compiled should use the same Python version as the package itself.

Programs which embed a Python interpreter must declare a Build-Depends on pythonX.Y-dev, where pythonX.Y is the python version the program builds against. It should be the current default python version unless the program does not work correctly with this version.

Dependencies for programs linking against the shared Python library will be automatically created by dpkg-shlibdeps. The libpythonX.Y.so.Z library the program is built against is provided by the pythonX.Y package.