At any given time, the package python will represent the current default Debian Python version.

The default Debian Python version should alway be the latest stable upstream release that can be integrated in the distribution.

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.0 and 2.0.1 are subminor versions of the same Python version 2.0, but Python 2.1 and 2.2 are indeed different versions.)

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

The set of currently supported python versions can be found in /usr/share/python/debian_defaults.

For every Python version provided in the distribution, the package pythonX.Y shall comprise a complete distribution for deployment of Python scripts and applications. The package includes the binary /usr/bin/pythonX.Y and all modules of the upstream Python distribution.

Excluded are any modules that depend on non-required packages, they will be provided in separate packages. Some tools and files for the development of Python modules are split off in a separate package pythonX.Y-dev. Documentation will be provided separately as well.

At any time, the python package must contain a symlink /usr/bin/python to the the appropriate binary /usr/bin/pythonX.Y. The python package must also depend on the appropriate pythonX.Y to ensure this binary is installed. The version of the python package must be greater than or equal to X.Y and smaller than X.Y+1.

The module search path for Debian has been amended to include a directory tree in /usr/local at the beginning of the path. By default, sys.path is searched in the following order: /usr/lib/pythonXY.zip /usr/lib/pythonX.Y /usr/lib/pythonX.Y/plat-linux2 /usr/lib/pythonX.Y/lib-tk /usr/lib/pythonX.Y/lib-dynload /usr/local/lib/pythonX.Y/site-packages /usr/lib/pythonX.Y/site-packages /var/lib/python-support/pythonX.Y /usr/lib/pythonX.Y/site-packages/module-dir /usr/lib/site-python

The use of the /usr/lib/site-python directory is deprecated. The directory may be dropped from the path in a future version. The /usr/lib/pythonXY.zip archive appeared in python2.3; it is not currently used in Debian. Modules should not install directly to the /var/lib/python-support directory; it is for use by .

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

TODO: Policy for documentation of third party packages.

Public modules should be packaged with a name of python-foo, where foo is the name of the module. 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 command 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 XS-Python-Version field in debian/control specifies the versions of Python supported by the package. This is used to track packages during Python transitions, and is also 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: all XS-Python-Version: current XS-Python-Version: current, >= X.Y XS-Python-Version: >= X.Y XS-Python-Version: >= A.B, << X.Y XS-Python-Version: A.B, X.Y Where "all" means the package supports any Python version available, and "current" means it supports Debian's current Python version. Explicit Versions or version ranges can also be used.

Your 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 dh_python 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 explicitely.

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 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.

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.

If a package provides any binary-independent modules (foo.py files), the corresponding bytecompiled 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 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.

Modules in private installation directories and in /usr/lib/site-python should be byte-compiled, when the default python version changes.

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 python-foo.

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 bytecompilation for programs that support any version of Python also apply to programs supporting only a single Python version. Modules to be bytecompiled 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 doesn't 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.