flux-python(1)

SYNOPSIS

flux python [--get-path] [--list-versions] [ARGS...]

flux pythonX.Y [--get-path] [ARGS...]

DESCRIPTION

flux python provides convenient access to the Python interpreter configured for the current Flux installation, with the Flux Python bindings automatically available for import.

When invoked without options, flux python prepends the Flux Python bindings installation path to PYTHONPATH and executes the configured Python interpreter with all remaining arguments. This allows running Python scripts or interactive sessions with immediate access to the correct flux module for the current Flux installation without manual PYTHONPATH manipulation.

The command also supports special options to get the path to the bindings as well as support discovery of available Python versions when bindings for multiple Python version may be installed.

By default, Flux installs Python bindings to a standard Python installation path (e.g., site-packages). However, prepending this entire directory to PYTHONPATH would place all modules in that location ahead of the user's existing Python path, potentially overriding other installed packages. To avoid this issue, Flux creates per-version symbolic links to only the Flux Python bindings in an isolated directory under the Flux library path. This isolated path is what flux python adds to PYTHONPATH and what --get-path reports, ensuring users can access Flux bindings without inadvertently affecting the import order of other Python modules.

OPTIONS

--get-path: Print the installation path of the Flux Python bindings for this Python version and exit. This reports the isolated path containing only Flux bindings, not the full Python site-packages directory, allowing the bindings to be added to PYTHONPATH without affecting the import order of other Python modules.

--list-versions: List available python bindings versions by looking for flux-pythonX.Y wrapper scripts in FLUX_EXEC_PATH. Each line of output shows a version-specific command (e.g., python3.10, python3.11) that can be invoked via flux pythonX.Y**. This option helps discover which Python versions have Flux bindings installed in multi-version environments.

VERSION-SPECIFIC COMMANDS

When multiple Flux installations are built against different Python versions, each installs a flux pythonX.Y command (e.g., flux python3.10, flux python3.11) corresponding to its target Python version. These commands provide explicit access to Flux bindings for specific Python versions.

The flux pythonX.Y commands accept the same --get-path option as flux python, allowing users to query the bindings path for any installed Python version:

$ flux python3.10 --get-path
/usr/lib/flux/python3.10

To discover which version-specific commands are available, use:

$ flux python --list-versions
python3.10
python3.11
python3.12

EXAMPLES

Run a Python script with Flux bindings available:

$ flux python myscript.py

Start an interactive Python session:

$ flux python
>>> import flux
>>> h = flux.Flux()

Get the path to default Flux Python bindings:

$ flux python --get-path
/usr/lib/flux/python3.11

Use a specific Python version:

$ flux python3.10 -c "import sys; print(sys.version)"
3.10.12 (main, Nov 20 2023, 15:14:05) [GCC 11.4.0]

Manually set PYTHONPATH for external tools:

$ export PYTHONPATH=$(flux python --get-path):$PYTHONPATH
$ python3 -c 'import flux; print(flux.Flux().attr_get("rank"))'
0

ENVIRONMENT

PYTHONPATH: The flux python command prepends the Flux bindings installation path to this environment variable before executing Python. Any existing PYTHONPATH entries are preserved.

FLUX_EXEC_PATH: Used by --list-versions to discover installed flux-pythonX.Y commands across all directories in the Flux command search path.

RESOURCES

Flux: http://flux-framework.org

Flux RFC: https://flux-framework.readthedocs.io/projects/flux-rfc

Issue Tracker: https://github.com/flux-framework/flux-core/issues