findpython

0.7.1 verified Tue May 12 auth: no python install: verified quickstart: stale

findpython is a Python utility library designed to locate various Python versions installed on your system. It is a modern rewrite of the `pythonfinder` project, simplifying the codebase while retaining core functionality. The current version is 0.7.1, and the project maintains an active release cadence with frequent bug fixes and feature enhancements.

pip install findpython

Common errors

error ModuleNotFoundError: No module named 'findpython' ↓

cause The `findpython` library is not installed in the current Python environment or the Python interpreter cannot locate it in its search path.

fix

Install the library using pip: pip install findpython

error AttributeError: 'NoneType' object has no attribute 'executable' ↓

cause This error occurs when `findpython.find()` is called but fails to locate a Python version matching the criteria, returning `None`. Subsequently, an attempt is made to access an attribute (like 'executable') on this `None` object.

fix

Always check if findpython.find() returned a PythonVersion object before accessing its attributes. For example:

import findpython

python_version = findpython.find(3, 9)
if python_version:
    print(python_version.executable)
else:
    print("Python 3.9 not found.")

error ImportError: cannot import name 'find_python_cmd' from 'findpython' ↓

cause This error often arises from confusion with the `findpython` R package or older versions/other libraries (like `pythonfinder`) that might have used a similar function name. The Python `findpython` library does not expose a top-level function named `find_python_cmd`.

fix

The primary functions in the Python findpython library are findpython.find() and findpython.find_all(). Use these functions directly from the imported findpython module:

import findpython

# To find a specific Python version
python_exe = findpython.find(major=3, minor=9)
print(python_exe)

# To find all Python versions
all_pythons = findpython.find_all()
for py in all_pythons:
    print(py.executable)

Warnings

breaking Version 0.5.0 dropped official support for Python 3.7. Users on Python 3.7 should either upgrade their Python environment or pin findpython to a version older than 0.5.0. ↓

fix Upgrade Python to 3.8 or newer, or pin `findpython<0.5.0`.

gotcha As of version 0.6.3, `findpython` prefers 64-bit Python interpreters over 32-bit ones when both are available and meet other criteria. This might alter the expected result if your system has mixed architectures and you rely on a specific 32-bit interpreter. ↓

fix Explicitly filter the results from `find_pythons()` based on the `is_64bit` attribute if you require a 32-bit Python, or ensure the desired interpreter is prioritized in your PATH/environment.

gotcha Version 0.7.0 introduced a feature to separate free-threaded Python versions from normal ones. While not strictly 'breaking', this change means that the `PythonVersion` objects returned might now include an indication of whether an interpreter is free-threaded, which could affect how you filter or interpret the results if you have such environments. ↓

fix Review your code if it makes assumptions about Python interpreter types or if you are specifically looking for/excluding free-threaded interpreters. The `PythonVersion` object's properties should be checked for free-threaded status.

gotcha The library searches for Python in various locations including PATH, pyenv, asdf, rye, uv, macOS Frameworks, and Windows registry. The order of preference can be complex, and `findpython` might not always return the exact Python you expect if multiple versions are present and configured differently across these sources. ↓

fix Inspect the `executable` path of the `PythonVersion` objects returned by `find_pythons()` to confirm it's the desired interpreter. For specific environments, ensure that the preferred Python is correctly configured in your system's PATH or environment variables.

breaking The `find_pythons()` function, a primary entry point for discovering Python interpreters, has been removed or renamed. This breaking change requires users to update their code to use the new API or pin to an older `findpython` version. ↓

fix Consult the official `findpython` library documentation for the current API to locate Python interpreters, or pin the `findpython` dependency to a version where `find_pythons()` is still available (e.g., `<0.X.Y`).

breaking The `find_pythons()` function was renamed to `find_all_pythons()`. ↓

fix Replace `findpython.find_pythons()` with `findpython.find_all_pythons()` in your code.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.11s 18.8M

3.10 slim (glibc) - - 0.07s 19M

3.11 alpine (musl) - - 0.28s 20.8M

3.11 slim (glibc) - - 0.16s 21M

3.12 alpine (musl) - - 0.15s 12.7M

3.12 slim (glibc) - - 0.15s 13M

3.13 alpine (musl) - - 0.15s 12.3M

3.13 slim (glibc) - - 0.14s 13M

3.9 alpine (musl) - - 0.09s 18.3M

3.9 slim (glibc) - - 0.07s 19M

Imports

findpython
```
import findpython
```
The primary module to import for accessing utility functions.
PythonVersion
```
from findpython.python_version import PythonVersion
```
The named tuple representing a found Python version, often returned by functions like `find_pythons()`.

Quickstart stale last tested: 2026-04-23

This example demonstrates how to find all installed Python versions and how to search for a specific major and minor version using the `findpython` library.

import findpython

# Find all Python versions on the system
pythons = findpython.find_pythons()
for p in pythons:
    print(f"Found Python: {p.executable} (Version: {p.major}.{p.minor}.{p.patch}, 64bit: {p.is_64bit})")

# Find a specific Python version (e.g., Python 3.9)
py39 = findpython.find_python(3, 9)
if py39:
    print(f"Found Python 3.9: {py39.executable}")
else:
    print("Python 3.9 not found.")