Choosing an interpreter

By default, tn-venv builds the environment from the interpreter that is running tn-venv itself. The -p / --python option overrides that, and accepts four different kinds of spec.

Spec grammar

Form	Examples	Meaning
path	C:\Python311\python.exe, ./bin/python3	probe this exact executable
version	3, 3.12, 3.12.1	any discoverable interpreter matching the version
command name	python3.12, pypy3.10	resolved on PATH, then matched as a version
implementation + version	pypy3.10, cpython-3.12	restrict by implementation

The formal grammar is:

spec      := [implementation] version ["-" arch]
implementation := "cpython" | "pypy" | "graalpy" | "python" | "py"
version   := major ["." minor ["." patch]]
arch      := "32" | "64"

Matching is prefix-based: -p 3 accepts any Python 3, -p 3.12 accepts any 3.12.x, and -p 3.12.1 demands exactly 3.12.1. python3.12 and plain 3.12 both imply CPython.

The option is repeatable, and the first satisfiable spec wins:

$ tn-venv -p 3.13 -p 3.12 -p 3.11

Discovery providers

When a spec is not a path, tn-venv enumerates candidate interpreters from six providers, in this order:

Provider	Source	Platforms
current	the interpreter running tn-venv	all
PATH	python, python3, python3.x, … found by PATH lookup	all
registry	PEP 514 registry keys under HKCU\Software\Python and HKLM\Software\Python	Windows
py-launcher	py -0p (the PEP 397 launcher)	Windows
uv	uv’s managed installs (UV_PYTHON_INSTALL_DIR, platform data dir)	all
pyenv	PYENV_ROOT/versions, ~/.pyenv/versions	all

Candidates are de-duplicated by resolved executable path, and a provider that fails (for example, py not installed) is skipped silently. Among the matching candidates, tn-venv picks the highest version, preferring the currently running interpreter on ties.

The Windows registry provider (PEP 514)

On Windows, interpreters may register themselves under Software\Python\<Company>\<Tag> in either HKEY_CURRENT_USER or HKEY_LOCAL_MACHINE. tn-venv reads the ExecutablePath value of the InstallPath subkey, falling back to <InstallPath>\python.exe. This is how the official python.org installers, the NuGet distribution, and most enterprise deployments advertise themselves.

Probing

Every candidate is probed by executing it with a small embedded script that prints a JSON description of itself (version, prefixes, architecture, whether the GIL is disabled, where its venv launcher binaries live, and so on). Probing is isolated (-I), bounded by a 30-second timeout, and cached for the lifetime of the process, so a dozen candidates cost very little.

An executable that exists but cannot be executed — wrong architecture, missing runtime, permission problem — is reported as unusable and skipped during spec matching, with the reason shown at -vv:

$ tn-venv -p 3.12 -vv
debug: probing interpreter path C:\Python312\python.exe
...

Listing everything tn-venv can see

$ tn-venv --list-pythons
==> discovering interpreters…
  3.14.7 (64-bit)  C:\Python314\python.exe                        — current
  3.14.7 (64-bit)  C:\Users\me\AppData\Roaming\uv\python\...\python.exe  — uv:cpython-3.14.7
  3.12.8 (64-bit)  C:\Python312\python.exe                        — registry:HKCU/PythonCore/3.12

Each row shows the probed version and bitness, the executable path, a [free-threaded] marker where applicable, and the provider that supplied the candidate.

Errors

When no candidate satisfies any spec, the command fails with exit code 1 and an InterpreterNotFoundError message listing every candidate that was probed:

error: no Python interpreter found for spec '9.99'
candidates probed:
  C:\Python314\python.exe (...)

Tip

If discovery picks a different interpreter than you expect, run tn-venv --list-pythons and pass the exact path with -p.