Python Interpreter Discovery

1.2.1 · active · verified Wed Apr 01

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.

Warnings

breaking Version 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.
gotcha Older 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.
gotcha Versions 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.
gotcha In 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.

Install

pip install python-discovery Install stable version

Imports

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.

Quickstart

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'.")

view raw JSON →