PYRS logo PYRS

Import and Stdlib Paths

Edit this page

Import-path behavior and stdlib root resolution in PYRS.

This page describes how PYRS chooses a CPython 3.14 stdlib root and what extra import entries are added in CLI and script execution.

Path Resolution Rules

Rule Behavior
PYRS_CPYTHON_LIB

When set, PYRS treats it as the explicit stdlib root, keeps stdlib imports isolated to that tree, and only borrows a host lib-dynload directory if the chosen root does not include one.

Binary-relative managed stdlib

Installed binaries first look next to the executable, preferring ../share/pyrs/stdlib/3.14.3/Lib and then older binary-relative layouts used by Homebrew/dev packaging.

GitHub installer data root

The shell installer stages bundled stdlib content under ${XDG_DATA_HOME:-~/.local/share}/pyrs/stdlib/3.14.3/Lib. The legacy ~/.local/share/pyrs/… location is still recognized for older installs.

Repo-local dev fallback.local/Python-3.14.3/Lib is accepted for local contributor/development workflows.
PYTHONHOMEFalls back to PYTHONHOME/lib/python3.14 when no managed or explicit root is selected.
Host CPython 3.14 rootsFramework/system CPython 3.14 locations on macOS and Linux are used as the final stdlib fallback.
Host lib-dynload fallbackUsed only when the selected stdlib root does not contain its own dynamic-loader directory.

Extra Import Entries

Source Behavior
Script modeThe executed script’s parent directory is prepended to import resolution.
-m modeThe current working directory is prepended before resolving the target module.
PYTHONPATHAdditional search entries are appended during startup path setup.
VIRTUAL_ENVDetected site-packages paths under the active virtualenv are appended when present.

Common Local Workflow

Shell
$ export PYRS_CPYTHON_LIB=.local/Python-3.14.3/Lib $ pyrs -c "import sys, dataclasses; print(sys.version.split()[0])"

Troubleshooting Imports

  • If a stdlib module is missing, verify PYRS_CPYTHON_LIB points to a valid CPython 3.14 Lib tree.
  • For GitHub-installer setups, verify the managed bundle exists under ${XDG_DATA_HOME:-~/.local/share}/pyrs/stdlib/3.14.3/Lib.
  • For Cargo or direct-archive installs, provide CPython 3.14 yourself or set PYRS_CPYTHON_LIB explicitly.
  • For environment-specific issues, test with pyrs -S -c ... to isolate startup import effects.
  • Keep virtualenv activation separate from parity harness runs if you need stable baseline behavior.