Registry / devops / python-discovery

python-discovery

library1.5.3pypypi✓ verified 27d ago

python-discovery is a Python library designed for robust discovery of Python interpreters installed on a machine. It can locate Python versions from various sources like system packages, pyenv, mise, asdf, uv, and the Windows registry (PEP 514). It verifies candidates and returns detailed metadata, with results cached for faster repeated lookups. The library is actively maintained, with frequent minor releases addressing bug fixes and feature enhancements. The current version is 1.2.1.

devops

pip install python-discovery

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · PYTHON-DISCOVERY

python-discovery

devopspythonv1.5.3

Install

1.7s avg

Import

173ms

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.5.3 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.180s · 18.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.166s · 19MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

get_interpreter

✓ from python_discovery import get_interpreter

The primary function for discovering Python interpreters.

DiskCache

✓ from python_discovery import DiskCache

Used to configure caching for discovery results.

KNOWN_ARCHITECTURES

✓ from python_discovery import KNOWN_ARCHITECTURES

Exposes a public API for known architectures, added in 1.2.1.

This quickstart demonstrates how to use `get_interpreter` to find Python installations based on version specifiers, leveraging `DiskCache` for performance. It attempts to find any Python 3 interpreter and then a specific range of Python 3 versions.

from pathlib import Path from python_discovery import DiskCache, get_interpreter import os # Define a cache root path; for a quickstart, we use a demo-specific path. # In a real application, consider a persistent user cache (e.g., ~/.cache/python-discovery). cache_root = Path.home() / ".cache" / "python-discovery-quickstart-demo" cache_root.mkdir(parents=True, exist_ok=True) cache = DiskCache(root=cache_root) # Discover any Python 3 interpreter available on the system print("Attempting to discover a Python 3.x interpreter...") python_3_interpreter = get_interpreter("python3", cache=cache) if python_3_interpreter: print(f"Found Python 3 interpreter: {python_3_interpreter.executable}") print(f"Version: {python_3_interpreter.version}") print(f"Prefix: {python_3_interpreter.prefix}") else: print("Could not find a Python 3 interpreter.") # Discover a specific Python version using PEP 440 specifier print("\nAttempting to discover Python >=3.9,<3.12...") specific_interpreter = get_interpreter(">=3.9,<3.12", cache=cache) if specific_interpreter: print(f"Found Python matching spec: {specific_interpreter.executable}") print(f"Version: {specific_interpreter.version}") else: print("Could not find a Python interpreter matching '>=3.9,<3.12'.")

Debug

Known issues

breakingVersion 1.0.0 was a significant rewrite of the library, fundamentally changing its internal architecture and likely its public API for early adopters. Users upgrading from pre-1.0.0 versions should review the changelog carefully.

fix

Review the `python-discovery` 1.0.0 release notes and adapt your code to the new API if upgrading from pre-1.0.0 versions.

affects: <1.0.0

gotchaOlder versions (prior to 1.2.0) might experience interpreter discovery timeouts in environments where Python processes take longer to respond. Version 1.2.0 increased the default query timeout to 15 seconds.

fix

Upgrade to version 1.2.0 or newer. If issues persist, check library documentation for how to configure longer timeouts if available in your version.

affects: <1.2.0

gotchaVersions prior to 1.1.2 had issues correctly matching prerelease Python versions (e.g., `3.10.0rc1`) against standard major.minor version specifiers. This could lead to valid interpreters not being discovered.

fix

Upgrade to version 1.1.2 or newer to ensure correct matching of prerelease Python versions.

affects: <1.1.2

gotchaIn versions before 1.1.2, the library might have left subprocess pipes undrained after killing timed-out discovery processes. This could potentially lead to resource leaks or hangs in certain scenarios.

fix

Upgrade to version 1.1.2 or newer to resolve potential subprocess resource handling issues.

affects: <1.1.2

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'python_discovery'

The `python-discovery` package has not been installed in the current Python environment.

fix

pip install python-discovery

ModuleNotFoundError: No module named 'discovery'

The user attempted to import the library using an incorrect module name; the correct module name is `python_discovery`.

fix

from python_discovery import discover_python_versions

NameError: name 'discover_python_versions' is not defined

The function `discover_python_versions` was called without first importing it from the `python_discovery` module.

fix

from python_discovery import discover_python_versions

TypeError: PythonVersion.__new__() missing 12 required positional arguments: 'major', 'minor', 'patch', 'is_prerelease', 'is_devrelease', 'is_postrelease', 'tag', 'architecture', 'implementation', 'is_64bit', 'distribution', and 'path'

The `PythonVersion` named tuple is intended to be returned by `discover_python_versions` and should not typically be instantiated directly by users.

fix

Call `discover_python_versions()` to get a list of `PythonVersion` objects instead of trying to create one manually.

Upgrade

Version history

1.5.3latest on PyPI · released Aug 24, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

16 hits · last 30 days

node

Resources

githubhttps://github.com/tox-dev/python-discovery ↗

packagehttps://pypi.org/project/python-discovery/ ↗

docshttps://python-discovery.readthedocs.io ↗

changeloghttps://github.com/tox-dev/python-discovery/releases ↗