ducktools: pythonfinder

Find local python installs on Windows/Linux/MacOS and find the latest installers from python.org for Windows and MacOS or sources for Linux (as python.org does not provide linux installers).

Requires Python >= 3.10 (but will discover older Python installs)

Download the zipapp here

It is also available as an application and library on PyPI. The simplest way to install this is with uv.

With uv:

• Install it as an application with uv tool install ducktools-pythonfinder
• Run once with uvx ducktools-pythonfinder
• Add it as a library to a project with uv add ducktools-pythonfinder
• Add it as a library for a script with uv add --script scriptname.py ducktools-pythonfinder
• test it in a repl with uv run --isolated --with ducktools-pythonfinder python

If you do not wish to use uv, you can also install as an application with pipx, or manually manage dependencies in pyproject.toml, inline script metadata or in virtual environments using pip.

Command Line Usage

ducktools-pythonfinder can be used as a module or as a bundled zipapp (as pythonfinder.pyz).

python pythonfinder.pyz or python -m ducktools.pythonfinder will provide a table of installed python versions and their respective folders. It will also indicate the python running the command if it is found, or the python that is the base for the venv running the command.

Python versions listed can be restricted by using the --max, --min and --compatible options to the command. These roughly translate to >= for min, < for max and ~= for compatible in python version specifiers.

Library Usage

Local installs

The module provides two main functions for searching for local python installs:

• get_python_installs is a generator that will yield each python version it discovers
• list_python_installs will take the python versions discovered by get_python_installs and return a sorted list from newest to oldest python version discovered.
  • For the purposes of sorting, prerelease versions are considered older than any released version.

On Windows these methods will search the registry for PEP514 recorded python installs before checking for any pyenv-win installs that have not been registered. Finally, if uv is available it will try to find Python installs managed by uv.

On Linux and MacOS this will search for pyenv installs first, if uv is available it will then try to find uv managed python installs. Finally it will search PATH for any other python* binaries that might be available.

If a python install is found twice (for instance a pyenv install in the windows registry) it will only be returned the first time it is found.

The python installs will be returned as instances of PythonInstall which will contain version info and executable path along with some other useful metadata.

Example:

import os.path
from ducktools.pythonfinder import list_python_installs

user_path = os.path.expanduser("~")

for install in list_python_installs():
    install.executable = install.executable.replace(user_path, "~")
    print(install)

Example Windows Output:

PythonInstall(version=(3, 12, 5, 'final', 0), executable='~\\.pyenv\\pyenv-win\\versions\\3.12.5\\python.exe', architecture='64bit', implementation='cpython', metadata={'DiplayName': 'Python 3.12 (64-bit)', 'SupportUrl': 'https://github.com/pyenv-win/pyenv-win/issues', 'SysArchitecture': '64bit', 'SysVersion': '3.12', 'Version': '3.12.5', 'InWindowsRegistry': True}, shadowed=False)
PythonInstall(version=(3, 12, 3, 'final', 0), executable='~\\.pyenv\\pyenv-win\\versions\\3.12.3\\python.exe', architecture='64bit', implementation='cpython', metadata={}, shadowed=False)
PythonInstall(version=(3, 11, 9, 'final', 0), executable='~\\.pyenv\\pyenv-win\\versions\\3.11.9\\python.exe', architecture='64bit', implementation='cpython', metadata={'DiplayName': 'Python 3.11 (64-bit)', 'SupportUrl': 'https://github.com/pyenv-win/pyenv-win/issues', 'SysArchitecture': '64bit', 'SysVersion': '3.11', 'Version': '3.11.9', 'InWindowsRegistry': True}, shadowed=False)
PythonInstall(version=(3, 10, 11, 'final', 0), executable='~\\.pyenv\\pyenv-win\\versions\\3.10.11\\python.exe', architecture='64bit', implementation='cpython', metadata={'DiplayName': 'Python 3.10 (64-bit)', 'SupportUrl': 'https://github.com/pyenv-win/pyenv-win/issues', 'SysArchitecture': '64bit', 'SysVersion': '3.10', 'Version': '3.10.11', 'InWindowsRegistry': True}, shadowed=False)
PythonInstall(version=(3, 9, 13, 'final', 0), executable='~\\.pyenv\\pyenv-win\\versions\\3.9.13\\python.exe', architecture='64bit', implementation='cpython', metadata={'DiplayName': 'Python 3.9 (64-bit)', 'SupportUrl': 'https://github.com/pyenv-win/pyenv-win/issues', 'SysArchitecture': '64bit', 'SysVersion': '3.9', 'Version': '3.9.13', 'InWindowsRegistry': True}, shadowed=False)
PythonInstall(version=(3, 8, 10, 'final', 0), executable='~\\.pyenv\\pyenv-win\\versions\\3.8.10\\python.exe', architecture='64bit', implementation='cpython', metadata={'DiplayName': 'Python 3.8 (64-bit)', 'SupportUrl': 'https://github.com/pyenv-win/pyenv-win/issues', 'SysArchitecture': '64bit', 'SysVersion': '3.8', 'Version': '3.8.10', 'InWindowsRegistry': True}, shadowed=False)
PythonInstall(version=(3, 13, 0, 'candidate', 1), executable='~\\.pyenv\\pyenv-win\\versions\\3.13.0rc1\\python.exe', architecture='64bit', implementation='cpython', metadata={}, shadowed=False)```

Finding venvs

There is now a submodule to search for virtual environments.

import os
from ducktools.pythonfinder.venv import list_python_venvs

for venv in list_python_venvs(recursive=False, search_parent_folders=True):
    print(venv.executable)

Why?

For the purposes of PEP723 script dependencies and other releated tools it may be useful to find another version of python other than the one currently running in order to satisfy the requires-python field. This tool is intended to search for potential python installs to attempt to satisfy such a requirement.

Isn't there already a 'pythonfinder' module?

That module appears to require searching for a specific version and will find venv pythons.

In contrast ducktools.pythonfinder simply yields python installs as they are discovered and will attempt to avoid returning virtualenv python installs (unless you are searching for venvs)