Skip to content
Back to top

# API reference

Self-contained Python interpreter discovery.

class python_discovery.ContentStore(*args, **kwargs)

  Bases: `Protocol`

  A store for reading and writing cached content.

  exists()

    Return whether the cached content exists.

    Return type:

      `bool`

  locked()

    Context manager that acquires an exclusive lock on this store.

    Return type:

      `Generator`[`None`]

  read()

    Read the cached content, or `None` if unavailable or corrupt.

    Return type:

      `dict` | `None`

  remove()

    Delete the cached content.

    Return type:

      `None`

  write(content)

    Persist content to the store.

    Parameters:

      content (`dict`) – interpreter metadata to cache.

    Return type:

      `None`

class python_discovery.DiskCache(root)

  Bases: `object`

  File-system based Python interpreter info cache (`<root>/py_info/4/<sha256>.json`).

  Parameters:

    root (`Path`) – root directory for the on-disk cache.

  py_info(path)

    Return the content store for the interpreter at path.

    Parameters:

      path (`Path`) – absolute path to a Python executable.

    Return type:

      `DiskContentStore`

  py_info_clear()

    Remove all cached interpreter information.

    Return type:

      `None`

class python_discovery.PyInfoCache(*args, **kwargs)

  Bases: `Protocol`

  Cache interface for Python interpreter information.

  py_info(path)

    Return the content store for the interpreter at path.

    Parameters:

      path (`Path`) – absolute path to a Python executable.

    Return type:

      `ContentStore`

  py_info_clear()

    Remove all cached interpreter information.

    Return type:

      `None`

class python_discovery.PythonInfo

  Bases: `object`

  Contains information for a Python interpreter.

  classmethod clear_cache(cache)

    Clear all cached interpreter information from cache.

    Parameters:

      cache (PyInfoCache) – the cache store to clear.

    Return type:

      None

  classmethod current(cache=None)

    Locate the current host interpreter information.

    Parameters:

      cache (PyInfoCache | None) – interpreter metadata cache; when `None` results are not cached.

    Return type:

      PythonInfo

  classmethod current_system(cache=None)

    Locate the current system interpreter information, resolving through any virtualenv layers.

    Parameters:

      cache (PyInfoCache | None) – interpreter metadata cache; when `None` results are not cached.

    Return type:

      PythonInfo

  discover_exe(cache, prefix, *, exact=True, env=None)

    Discover a matching Python executable under a given prefix directory.

    Parameters:

      - cache (PyInfoCache) – interpreter metadata cache.

      - prefix (str) – directory prefix to search under.

      - exact (bool) – when `True`, require an exact version match.

      - env (Mapping[str, str] | None) – environment mapping; defaults to `os.environ`.

    Return type:

      PythonInfo

  classmethod from_dict(data)

    Reconstruct a `PythonInfo` from a plain dictionary.

    Parameters:

      data (`dict`[`str`, `object`]) – dictionary produced by `to_dict()`.

    Return type:

      `PythonInfo`

  classmethod from_exe(exe, cache=None, *, raise_on_error=True, ignore_cache=False, resolve_to_host=True, env=None)

    Get the python information for a given executable path.

    Parameters:

      - exe (str) – path to the Python executable.

      - cache (PyInfoCache | None) – interpreter metadata cache; when `None` results are not cached.

      - raise_on_error (bool) – raise on failure instead of returning `None`.

      - ignore_cache (bool) – bypass the cache and re-query the interpreter.

      - resolve_to_host (bool) – resolve through virtualenv layers to the system interpreter.

      - env (Mapping[str, str] | None) – environment mapping; defaults to `os.environ`.

    Return type:

      PythonInfo | None

  classmethod from_json(payload)

    Deserialize interpreter information from a JSON string.

    Parameters:

      payload (`str`) – JSON produced by `to_json()`.

    Return type:

      `PythonInfo`

  install_path(key)

    Return the relative installation path for a given installation scheme key.

    Parameters:

      key (`str`) – sysconfig installation scheme key (e.g. `"scripts"`, `"purelib"`).

    Return type:

      `str`

  property is_old_virtualenv: bool

    `True` if this interpreter runs inside an old-style virtualenv (has `real_prefix`).

  property is_venv: bool

    `True` if this interpreter runs inside a PEP 405 venv (has `base_prefix`).

  property machine: str

    Return the instruction set architecture (ISA) derived from `sysconfig.get_platform()`.

  property python_name: str

    The python executable name as `pythonX.Y` (e.g. `python3.13`).

  classmethod resolve_to_system(cache, target)

    Walk virtualenv/venv prefix chains to find the underlying system interpreter.

    Parameters:

      - cache (PyInfoCache | None) – interpreter metadata cache; when `None` results are not cached.

      - target (PythonInfo) – the interpreter to resolve.

    Return type:

      PythonInfo

  satisfies(spec, *, impl_must_match)

    Check if a given specification can be satisfied by this python interpreter instance.

    Parameters:

      - spec (PythonSpec) – the specification to check against.

      - impl_must_match (bool) – when `True`, the implementation name must match exactly.

    Return type:

      bool

  property spec: str

    A specification string identifying this interpreter (e.g. `CPython3.13.2-64-arm64`).

  sysconfig_path(key, config_var=None, sep='/')

    Return the sysconfig install path for a scheme key, optionally substituting config variables.

    Parameters:

      - key (`str`) – sysconfig path key (e.g. `"purelib"`, `"include"`).

      - config_var (`dict`[`str`, `str`] | `None`) – replacement mapping for sysconfig variables; when `None` uses the interpreter’s own values.

      - sep (`str`) – path separator to use in the result.

    Return type:

      `str`

  property system_exec_prefix: str

    The exec prefix of the system Python this interpreter is based on.

  property system_include: str

    The path to the system include directory for C headers.

  property system_prefix: str

    The prefix of the system Python this interpreter is based on.

  to_dict()

    Convert this interpreter information to a plain dictionary.

    Return type:

      `dict`[`str`, `object`]

  to_json()

    Serialize this interpreter information to a JSON string.

    Return type:

      `str`

  property version_release_str: str

    The release version as `major.minor` string (e.g. `3.13`).

  property version_str: str

    The full version as `major.minor.micro` string (e.g. `3.13.2`).

class python_discovery.PythonSpec(str_spec, implementation, major, minor, micro, architecture, path, *, free_threaded=None, machine=None, version_specifier=None)

  Bases: `object`

  Contains specification about a Python Interpreter.

  Parameters:

    - str_spec (`str`) – the raw specification string as provided by the caller.

    - implementation (`str` | `None`) – interpreter implementation name (e.g. `"cpython"`, `"pypy"`), or `None` for any.

    - major (`int` | `None`) – required major version, or `None` for any.

    - minor (`int` | `None`) – required minor version, or `None` for any.

    - micro (`int` | `None`) – required micro (patch) version, or `None` for any.

    - architecture (`int` | `None`) – required pointer-size bitness (`32` or `64`), or `None` for any.

    - path (`str` | `None`) – filesystem path to a specific interpreter, or `None`.

    - free_threaded (`bool` | `None`) – whether a free-threaded build is required, or `None` for any.

    - machine (`str` | `None`) – required ISA (e.g. `"arm64"`), or `None` for any.

    - version_specifier (`SimpleSpecifierSet` | `None`) – version specifier constraints, or `None`.

  classmethod from_string_spec(string_spec)

    Parse a string specification into a `PythonSpec`.

    Parameters:

      string_spec (`str`) –

      an interpreter spec — an absolute path, a version string, an implementation prefix, or a version specifier.

    Return type:

      `PythonSpec`

  generate_re(*, windows, all_implementations=False)

    Generate a regular expression for matching interpreter filenames.

    Parameters:

      - windows (`bool`) – if `True`, require a `.exe` suffix.

      - all_implementations (`bool`) – when `True` and the spec does not constrain the implementation, match every filename in `KNOWN_IMPLEMENTATIONS` instead of only `python`. Used by enumeration APIs.

    Return type:

      `Pattern`

  property is_abs: bool

    `True` if the spec refers to an absolute filesystem path.

  satisfies(spec)

    Check if this spec is compatible with the given spec (e.g. PEP-514 on Windows).

    Parameters:

      spec (`PythonSpec`) – the requirement to check against.

    Return type:

      `bool`

class python_discovery.SimpleSpecifier(*, spec_str, operator, version_str, is_wildcard, wildcard_precision, version)

  Bases: `object`

  Simple PEP 440-like version specifier using only standard library.

  Parameters:

    - spec_str (`str`) – the original specifier string (e.g. `>=3.10`).

    - operator (`str`) – the comparison operator (`==`, `>=`, `<`, etc.).

    - version_str (`str`) – the version portion of the specifier, without the operator.

    - is_wildcard (`bool`) – `True` if the specifier uses a wildcard suffix (`.*`).

    - wildcard_precision (`int` | `None`) – number of version components before the wildcard, or `None`.

    - version (`SimpleVersion` | `None`) – the parsed version, or `None` if parsing failed.

  contains(version_str)

    Check if a version string satisfies this specifier.

    Parameters:

      version_str (`str`) – the version string to test.

    Return type:

      `bool`

  classmethod from_string(spec_str)

    Parse a single PEP 440 specifier (e.g. `>=3.10`).

    Parameters:

      spec_str (`str`) – the specifier string to parse.

    Return type:

      `SimpleSpecifier`

  is_wildcard: bool
  operator: str
  spec_str: str
  version: SimpleVersion | None
  version_str: str
  wildcard_precision: int | None

class python_discovery.SimpleSpecifierSet(*, specifiers_str, specifiers)

  Bases: `object`

  Simple PEP 440-like specifier set using only standard library.

  Parameters:

    - specifiers_str (`str`) – the original comma-separated specifier string.

    - specifiers (`tuple`[`SimpleSpecifier`, `...`]) – the parsed individual specifiers.

  contains(version_str)

    Check if a version satisfies all specifiers in the set.

    Parameters:

      version_str (`str`) – the version string to test.

    Return type:

      `bool`

  classmethod from_string(specifiers_str='')

    Parse a comma-separated PEP 440 specifier string (e.g. `>=3.10,<4`).

    Parameters:

      specifiers_str (`str`) – the specifier string to parse.

    Return type:

      `SimpleSpecifierSet`

  specifiers: tuple[SimpleSpecifier, ...]
  specifiers_str: str

class python_discovery.SimpleVersion(*, version_str, major, minor, micro, pre_type, pre_num, release)

  Bases: `object`

  Simple PEP 440-like version parser using only standard library.

  Parameters:

    - version_str (`str`) – the original version string.

    - major (`int`) – major version number.

    - minor (`int`) – minor version number.

    - micro (`int`) – micro (patch) version number.

    - pre_type (`str` | `None`) – pre-release label (`"a"`, `"b"`, or `"rc"`), or `None`.

    - pre_num (`int` | `None`) – pre-release sequence number, or `None`.

    - release (`tuple`[`int`, `int`, `int`]) – the `(major, minor, micro)` tuple.

  classmethod from_string(version_str)

    Parse a PEP 440 version string (e.g. `3.12.1`).

    Parameters:

      version_str (`str`) – the version string to parse.

    Return type:

      `SimpleVersion`

  major: int
  micro: int
  minor: int
  pre_num: int | None
  pre_type: str | None
  release: tuple[int, int, int]
  version_str: str

python_discovery.get_interpreter(key, try_first_with=None, cache=None, env=None, predicate=None)

  Find a Python interpreter matching key.

  Iterates over one or more specification strings and returns the first interpreter that satisfies the spec and passes the optional predicate.

  Parameters:

    - key (`str` | `Sequence`[`str`]) –

      interpreter specification string(s) — an absolute path, a version (`3.12`), an implementation prefix (`cpython3.12`), or a version specifier (`>=3.10`). When a sequence is given each entry is tried in order.

    - try_first_with (`Iterable`[`str`] | `None`) – executables to probe before the normal discovery search.

    - cache (`PyInfoCache` | `None`) – interpreter metadata cache; when `None` results are not cached.

    - env (`Mapping`[`str`, `str`] | `None`) – environment mapping for `PATH` lookup; defaults to `os.environ`.

    - predicate (`Callable`[[`PythonInfo`], `bool`] | `None`) – optional callback applied after an interpreter matches the spec. Return `True` to accept the interpreter, `False` to skip it and continue searching.

  Return type:

    `PythonInfo` | `None`

  Returns:

    the first matching interpreter, or `None` if no match is found.

python_discovery.iter_interpreters(key=None, try_first_with=None, cache=None, env=None, predicate=None)

  Yield every interpreter on the system that satisfies key.

  Iteration order is discovery order: `try_first_with` paths first, then the running interpreter, then `PATH` (left to right), then UV-managed installs. Results are deduplicated by the resolved real path of the underlying system interpreter, so symlinked aliases (`/bin` vs `/usr/bin`) and venvs that symlink to a base interpreter collapse to a single entry. Callers that want a different ordering should sort the result.

  Parameters:

    - key (`str` | `Sequence`[`str`] | `None`) – interpreter specification — same syntax as `get_interpreter()`. `None` enumerates every Python implementation python-discovery knows about (see `KNOWN_IMPLEMENTATIONS`).

    - try_first_with (`Iterable`[`str`] | `None`) – executables to probe before the normal discovery search.

    - cache (`PyInfoCache` | `None`) – interpreter metadata cache; when `None` results are not cached. Strongly recommended for enumeration, which interrogates every candidate as a subprocess on a cold cache.

    - env (`Mapping`[`str`, `str`] | `None`) – environment mapping for `PATH` lookup; defaults to `os.environ`.

    - predicate (`Callable`[[`PythonInfo`], `bool`] | `None`) – optional filter applied after the spec match; return `True` to include the interpreter.

  Return type:

    `Iterator`[`PythonInfo`]

python_discovery.normalize_isa(isa)

  Normalize an ISA (instruction set architecture) string to a canonical form.

  Known aliases are mapped (e.g. `amd64` → `x86_64`, `aarch64` → `arm64`). Unrecognized values are lowercased and returned as-is.

  Parameters:

    isa (`str`)

  Return type:

    `str`