Python maintenance

This page explains python upgrading, especially multislot preliminaries and actual procedure.

Basically you don't have to worry much. Basic instruction will appear in the emerge log.

In short
If you're not sure, install only one slot of python-2.x, not python-3. In that case, the following should work: General upgrading procedure of python

is something like ; it checks packages dependent on python, and automatically runs necessary to update them. It's a good idea to pass for example to see which packages will be re-emerged.

Basic facts

 * Python components: There're core python(s) (= ), python applications, and python libraries / modules not in core python. Applications and modules consist of pure scripts ( and often byte-compiled files and ), and natively compiled binaries.


 * Versions and Compatibility: Basically, pure python scripts are upward compatible, but Python3 (formerly aka py3k) is incompatible with Python2. In Gentoo, python is multislot, and you can install several python-x.y. Read the entire page carefully if you have multislot, even if all you have is python-2.


 * Don't install python-3 if unsure: If you're not sure, don't install python-3 yet. Many python codes are still python-2. Though it's safe to install python-3, you'll have to read this page and understand the Gentoo situation.


 * Necessary procedures in Gentoo: Two things have to be done in upgrading.
 * Maintenance of /usr/bin: For example, assume you have pythons 2.6, 2.7, and 3.1. Then under, you have:
 * (A symlink)
 * and (Symlinks)
 * ,, and . (True executables)
 * There's also . Please someone explain it.
 * They can be maintained by . Basically it's symlink issue, so you can do it manually even in worst situations.


 * Maintenance of modules: Most python modules, and some python applications, install version-specific files under . They include not only libraries, but also pure scripts, too. They can be handled by  command.
 * Portage itself doesn't have python-version dependent installation, so it's quite safe. (As long as you have python2. If you want to use python-3 for portage, enable the USE flag .)

Procedure
Read the section above first.

Some additional notes: (At least for . Need update for .)
 * By default, builds packages for eselected pythons.  detects the mismatch with installed support for python-version and eselect. So run  before . You can statically override the behavior with  as explained below.
 * When you have python-3.x and try to upgrade from python-2.6 to python-2.7, you should add to python-updater:

Multislot configuration
Notice: This section is obsolete since Nov 2012. Read the official documentation python-r1 User's Guide and python-r1 in the official wiki.

Caveat: read carefully. You don't need it if it's single slot, and probably nor for multislot.

Some python modules and applications (are supposed to) support multiple versions of python. You can set for example in  to insturct emerge to build packages for each of these versions of pythons.

After you set, probably you want to run python-updater.

In reality, many packages don't work with and eselect. See this blog post in 2010 by Gilles Dartiguelongue.

Python interpreter choice is global only
As explained above, python interpreters under are chosen statically with eselect. There's no per-package choice, i.e., you can't choose which Gentoo package run with which version of python.

Ebuild grammar
For how to write python related ebuilds, see Gentoo Python Developers Guide.