Troubleshooting

Under Construction

Diagnose and resolve common PySH issues.

Common issues

pysh: command not found

After installing with pip, the pysh command may not be on your PATH if the user scripts directory is not included. Run:

Fix PATH

# Find where pip installs scripts

$ python3 -m site --user-base

/home/user/.local

# Add to PATH in your shell rc file

$ echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

$ source ~/.bashrc

Note: If you install PySH with uv tool install pysh-shell, uv manages the PATH automatically.

Python version too old

PySH requires Python 3.12 or later. If your system Python is older, install a newer version via your package manager or use pyenv to manage multiple Python versions.

WSL2 setup

Info: PySH is Unix-like first. The supported Windows path today is WSL2 with full PySH semantics. Native Windows support is a future roadmap item.

✓Install WSL2 with Ubuntu 22.04 or Debian 12 from the Microsoft Store.
✓Ensure Python 3.12+ is available: sudo apt install python3.13
✓Install PySH: pip install pysh-shell or uv tool install pysh-shell
✓Add ~/.local/bin to PATH if needed (see above)
✓Launch with: pysh

Plugin errors

Plugin not loading

✓Verify the plugin package is installed: pip show plugin-name
✓Check the plugin name in .pysh.toml matches the installed package name exactly
✓Run pysh --debug to see verbose plugin load messages
✓Check for Python version compatibility issues in the plugin package

Plugin command not found

If a plugin loads but its commands are not available, the plugin may not have registered correctly. Check the plugin's plugin.toml to ensure command names match the decorated functions.

Getting help

✓Open an issue on GitHub: github.com/SSobol77/pysh-shell/issues
✓Join the community on Telegram: @PyshTerminal
✓Check the PySH Academy for guided troubleshooting lessons