Troubleshooting

Common PYRS setup, import, REPL, and diagnostics troubleshooting paths.

Use this page to quickly isolate common runtime, import, and diagnostics issues.

Import and Startup Issues

Symptom	Checks
Stdlib import fails unexpectedly	Verify `PYRS_CPYTHON_LIB` points to a valid CPython 3.14 `Lib/` tree, or check the managed bundle under `${XDG_DATA_HOME:-~/.local/share}/pyrs/stdlib/3.14.3/Lib`.
Startup fails on `site` import	Run with `-S` to isolate startup behavior, then validate stdlib root contents.
`-I` or `-E` did not ignore path-related env vars	Those flags are currently compatibility no-ops except for suppressing `PYTHONWARNINGS` ingest.
Different imports in virtualenv vs non-virtualenv runs	Check whether `VIRTUAL_ENV` is active and contributing `site-packages` entries.

Diagnostics and Parse Failures

Symptom	Checks
Unexpected syntax error formatting	Compare PYRS output with CPython for the same minimal snippet and mode (`-c` vs file).
Missing caret ranges	Check if startup used `-X no_debug_ranges` (caret range metadata disabled).
Runtime traceback shape mismatch	Capture complete output and include both PYRS and CPython traces in report.

Fast Triage Commands

Shell

  $ pyrs --version  $ pyrs -c "import sys; print(sys.version)"  $ pyrs -S -c "import sys; print(sys.path)"  $ pyrs --ast path/to/reproducer.py  $ pyrs --bytecode path/to/reproducer.py

Bug Report Checklist

Provide a minimal reproducer snippet or file.
Include exact invocation mode and flags used.
Include environment variables that influence startup/import behavior.
Provide both CPython and PYRS output for parity issues.
Include platform and architecture details (for example macOS arm64, Linux x86_64).