Python

This page contains changes which are not marked for translation.

Resources

Project

Home

Official documentation

Package information

Wikipedia

GitHub

Official project wiki

#python (webchat)

comp.lang.python (weblink)

r/Python

Python is an extremely popular cross-platform object oriented programming language.

Python powers Portage, eselect, equery, and many other tools in Gentoo.

Installation

Since Python is so integral to Gentoo there is little chance it is not installed. Doing so would be like removing the heart from Gentoo. There are occasions where Python must be recompiled in order to add new features or to upgrade.

USE flags

USE flags for dev-lang/python Freethreading (no-GIL) version of Python programming language

`+ensurepip`	Install the ensurepip module that uses bundled wheels to bootstrap pip and setuptools (if disabled, it will be only possible to use venv `--without-pip`)
`+ncurses`	Add ncurses support (console display library)
`+readline`	Enable support for libreadline, a GNU line-editing library that almost everyone wants
`+sqlite`	Add support for sqlite - embedded sql database
`+ssl`	Add support for SSL/TLS connections (Secure Socket Layer / Transport Layer Security)
`+xml`	Add support for XML files
`berkdb`	Add support for sys-libs/db (Berkeley DB for MySQL)
`bluetooth`	Build Bluetooth protocol support in socket module
`build`	!!internal use only!! DO NOT SET THIS FLAG YOURSELF!, used for creating build images and the first half of bootstrapping [make stage1]
`debug`	Enable extra debug codepaths, like asserts and extra output. If you want to get meaningful backtraces see https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Backtraces
`examples`	Install examples, usually source code
`gdbm`	Add support for sys-libs/gdbm (GNU database libraries)
`jit`	Enable experimental Just-In-Time compilation support.
`libedit`	Link readline extension against dev-libs/libedit instead of sys-libs/readline
`pgo`	Optimize the build using Profile Guided Optimization (PGO) by running Python's test suite and collecting statistics based on its performance. This will take longer to build.
`test`	Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)
`tk`	Add support for Tk GUI toolkit
`valgrind`	Disable pymalloc when running under dev-debug/valgrind is detected (may incur minor performance penalty even when valgrind is not used)
`verify-sig`	Verify upstream signatures on distfiles
`wininst`	Install Windows executables required to create an executable installer for MS Windows

Data provided by the Gentoo Package Database · Last update: 2025-03-24 10:22 More information about USE flags

Emerge

Python is slotted, which means that more than one Python version can be installed on a Gentoo system at the same time. Select the version to install by using an : (colon) and the package atom followed by one of the slot numbers:

For example, to install Python 3.8:

root #emerge --ask dev-lang/python:3.8

Configuration

Setting the active interpreter

The default (non-versioned) active interpreter is controlled through package dev-lang/python-exec. See python-exec wiki

Each time dev-lang/python-exec is emerged/rebuilt, use dispatch-conf, cfg-update or similar to accept or deny proposed modification to /etc/python-exec/python-exec.conf (that control the default Python interpreter)

Note
Python preference to follow PYTHON_TARGETS official statement - 2021-01-30

The older way to change to the active Python (non-versioned) interpreter using the eselect python command will remain as a wrapper to python-exec.conf modification if app-eselect/eselect-python is in the @world set. See eselect-python wiki

Version upgrade

Note
Python 2.7 has reached its end-of-life by January 1, 2020, as per this official statement.

Version upgrades can be elective, or may have to happen due to a profile update.

Profile update

When a Python version becomes deprecated, or is no longer supported, it may cause a profile update to set the PYTHON_SINGLE_TARGET to a higher version. This may cause emerge conflicts when updating a system.

The easiest way to handle this is to add the new Python version to the PYTHON_TARGETS, e.g. for the transition from python3_7 to python3_8:

FILE /etc/portage/package.use

*/* PYTHON_TARGETS: python3_7 python3_8

Then update the system:

root #emerge --ask --update --newuse --deep @world

Remove the support for the previous Python version, by removing the line added to /etc/portage/package.use and rebuild the system again.

Elective version upgrade

Users may select to upgrade their Python version also by choice. Before starting ensure that the system is up to date:

root #emerge --ask --update --newuse --deep @world

To make system packages be rebuilt using the new Python implementation update the PYTHON_TARGETS and PYTHON_SINGLE_TARGET variables in /etc/portage/package.use. For example, when updating from Python 3.6 to 3.7:

FILE /etc/portage/package.use

*/* PYTHON_TARGETS: python3_7
*/* PYTHON_SINGLE_TARGET: -* python3_7

Then update the system again using the --changed-use --deep options:

root #emerge --ask --changed-use --deep @world

You may be asked to update any remaining python_targets_python3_6 USE flags as well.

Note that some popular packages still require PYTHON_SINGLE_TARGET variable to be set to python2_7 due to various dependencies.

Cleanup

As of Jan 19, 2021, the information in this section is probably outdated. You can help the Gentoo community by verifying and updating this section.

Once the upgrade has completed, old Python implementations can be removed from the system using:

root #emerge --ask --depclean dev-lang/python

After depclean eselect python list will still show old Python versions if they were previously selected, to remove these entries run the following command:

root #eselect python cleanup

Note
The old python-updater has been removed from the Gentoo ebuild repository by this commit.

Usage

Invocation

user $python --help

Expand

usage: python3.9 [option] ... [-c cmd | -m mod | file | -] [arg] ...
Options and arguments (and corresponding environment variables):
-b     : issue warnings about str(bytes_instance), str(bytearray_instance)
         and comparing bytes/bytearray with str. (-bb: issue errors)
-B     : don't write .pyc files on import; also PYTHONDONTWRITEBYTECODE=x
-c cmd : program passed in as string (terminates option list)
-d     : turn on parser debugging output (for experts only, only works on
         debug builds); also PYTHONDEBUG=x
-E     : ignore PYTHON* environment variables (such as PYTHONPATH)
-h     : print this help message and exit (also --help)
-i     : inspect interactively after running script; forces a prompt even
         if stdin does not appear to be a terminal; also PYTHONINSPECT=x
-I     : isolate Python from the user's environment (implies -E and -s)
-m mod : run library module as a script (terminates option list)
-O     : remove assert and __debug__-dependent statements; add .opt-1 before
         .pyc extension; also PYTHONOPTIMIZE=x
-OO    : do -O changes and also discard docstrings; add .opt-2 before
         .pyc extension
-q     : don't print version and copyright messages on interactive startup
-s     : don't add user site directory to sys.path; also PYTHONNOUSERSITE
-S     : don't imply 'import site' on initialization
-u     : force the stdout and stderr streams to be unbuffered;
         this option has no effect on stdin; also PYTHONUNBUFFERED=x
-v     : verbose (trace import statements); also PYTHONVERBOSE=x
         can be supplied multiple times to increase verbosity
-V     : print the Python version number and exit (also --version)
         when given twice, print more information about the build
-W arg : warning control; arg is action:message:category:module:lineno
         also PYTHONWARNINGS=arg
-x     : skip first line of source, allowing use of non-Unix forms of #!cmd
-X opt : set implementation-specific option. The following options are available:

         -X faulthandler: enable faulthandler
         -X oldparser: enable the traditional LL(1) parser; also PYTHONOLDPARSER
         -X showrefcount: output the total reference count and number of used
             memory blocks when the program finishes or after each statement in the
             interactive interpreter. This only works on debug builds
         -X tracemalloc: start tracing Python memory allocations using the
             tracemalloc module. By default, only the most recent frame is stored in a
             traceback of a trace. Use -X tracemalloc=NFRAME to start tracing with a
             traceback limit of NFRAME frames
         -X importtime: show how long each import takes. It shows module name,
             cumulative time (including nested imports) and self time (excluding
             nested imports). Note that its output may be broken in multi-threaded
             application. Typical usage is python3 -X importtime -c 'import asyncio'
         -X dev: enable CPython's "development mode", introducing additional runtime
             checks which are too expensive to be enabled by default. Effect of the
             developer mode:
                * Add default warning filter, as -W default
                * Install debug hooks on memory allocators: see the PyMem_SetupDebugHooks() C function
                * Enable the faulthandler module to dump the Python traceback on a crash
                * Enable asyncio debug mode
                * Set the dev_mode attribute of sys.flags to True
                * io.IOBase destructor logs close() exceptions
         -X utf8: enable UTF-8 mode for operating system interfaces, overriding the default
             locale-aware mode. -X utf8=0 explicitly disables UTF-8 mode (even when it would
             otherwise activate automatically)
         -X pycache_prefix=PATH: enable writing .pyc files to a parallel tree rooted at the
             given directory instead of to the code tree

--check-hash-based-pycs always|default|never:
    control how Python invalidates hash-based .pyc files
file   : program read from script file
-      : program read from stdin (default; interactive mode if a tty)
arg ...: arguments passed to program in sys.argv[1:]

Other environment variables:
PYTHONSTARTUP: file executed on interactive startup (no default)
PYTHONPATH   : ':'-separated list of directories prefixed to the
               default module search path.  The result is sys.path.
PYTHONHOME   : alternate <prefix> directory (or <prefix>:<exec_prefix>).
               The default module search path uses <prefix>/lib/pythonX.X.
PYTHONPLATLIBDIR : override sys.platlibdir.
PYTHONCASEOK : ignore case in 'import' statements (Windows).
PYTHONUTF8: if set to 1, enable the UTF-8 mode.
PYTHONIOENCODING: Encoding[:errors] used for stdin/stdout/stderr.
PYTHONFAULTHANDLER: dump the Python traceback on fatal errors.
PYTHONHASHSEED: if this variable is set to 'random', a random value is used
   to seed the hashes of str and bytes objects.  It can also be set to an
   integer in the range [0,4294967295] to get hash values with a
   predictable seed.
PYTHONMALLOC: set the Python memory allocators and/or install debug hooks
   on Python memory allocators. Use PYTHONMALLOC=debug to install debug
   hooks.
PYTHONCOERCECLOCALE: if this variable is set to 0, it disables the locale
   coercion behavior. Use PYTHONCOERCECLOCALE=warn to request display of
   locale coercion and locale compatibility warnings on stderr.
PYTHONBREAKPOINT: if this variable is set to 0, it disables the default
   debugger. It can be set to the callable of your debugger of choice.
PYTHONDEVMODE: enable the development mode.
PYTHONPYCACHEPREFIX: root directory for bytecode cache (pyc) files.

A specific version of the Python interpreter can be invoked from the command-line directly by running:

user $python3.9

Python can be used to write scripts, with the appropriate shebang. To execute a script with Python 3.10, for example, use the following header:

FILE testscript.py

#!/usr/bin/env python3.10
...

External resources

Gentoo Python Guide, complete documentation for the Python ecosystem in Gentoo.
News item - Python 3.7 to become the default target
Python preference to follow PYTHON_TARGETS
Pipenv - for managing local installations of python packages (also in portage tree dev-python/pipenv)