Troubleshooting

Deterministic recovery paths for the stable PySH v1 contract.

Common issues

pysh: command not found

A user-level PyPI install may place console scripts under a directory that is not on PATH.

Inspect user installation paths

$ python3.13 -m site --user-base

/home/user/.local

$ python3.13 -m pip show pysh-shell

$ command -v pysh

Python version too old

PySH requires CPython 3.13.0 or newer. A supported operating-system family does not override the interpreter floor.

Check interpreter

$ python3 --version

$ python3.13 --version

$ pysh --version

Broken or untrusted user configuration

Start PySH with the explicit no-user-configuration policy. This skips user rc files, TOML, plugin configuration, plugin discovery/import, and startup hooks while keeping inherited process environment variables intact.

Recovery startup

$ pysh --no-rc

$ pysh --no-rc -c "echo recovery-ok"

Plugin errors

Trusted plugin not loading

✓Confirm the plugin is a direct .py file under ~/.config/pysh/plugins/
✓Confirm the module defines exactly one valid plugin class
✓Confirm name, version, and api_version are valid for Plugin API 1.0
✓Enable the plugin explicitly with shell.enable_plugin("name") in ~/.pyshrc.py
✓For .pysh/plugins/ project plugins, also call shell.enable_project_plugins() explicitly
✓Use --debug or --diagnostics-json to inspect redacted startup diagnostics

Plugin failure versus isolation

Trusted Plugin API callbacks run in-process and are contained at their registration/callback boundaries. The separate isolated-plugin runtime uses a subprocess, bounded IPC, capabilities, and resource controls, but is not an OS sandbox.

FreeBSD package ABI mismatch

Warning: Do not force-install the published reference .pkg across an incompatible FreeBSD ABI. Use Python packaging or build the canonical package on the compatible host instead.

WSL and Windows

Info: PySH v1 does not claim native Windows support. Inside WSL, use the support contract of the Linux distribution running in WSL and ensure CPython 3.13+ plus the required Unix facilities are available.

Terminal fallback behavior

✓Interactive raw editing requires a suitable terminal and TERM value
✓TERM=dumb uses the documented plain/readline fallback path
✓NO_COLOR or PYSH_COLOR=0 disables ANSI color without changing command semantics
✓Terminal restoration failures are errors and must not be hidden as successful execution

Structured diagnostics

Diagnostics

$ pysh --debug -c "echo hi"

$ pysh --diagnostics-json -c "echo hi"

$ pysh --audit-log ~/.local/state/pysh-audit.jsonl -c "echo hi"

Diagnostics use the centralized redaction policy. Audit logging is opt-in and uses a private file contract; normal command stdout/stderr is not written into the audit log.

Getting help

✓GitHub issues: github.com/SSobol77/pysh/issues
✓Latest release: github.com/SSobol77/pysh/releases/latest
✓Telegram community: @PyshTerminal