Getting Started

Understand the stable PySH v1 contract before you install or automate with it.

Note: Current stable release: 1.0.0. PySH requires CPython 3.13 or newer and targets supported Unix families. It is not a /bin/sh provider.

What is PySH?

PySH (pysh-shell) is a Python-first interactive shell and native script runner for developers, system administrators, and DevOps engineers. It combines normal Unix command execution with persistent Python execution, shell-oriented scripting, layered configuration, a versioned plugin API, structured diagnostics, and release-verification tooling.

PySH is designed to keep command-line workflows familiar while moving larger automation logic into real Python. It does not require you to choose between a shell session and a separate Python REPL for every task.

Compatibility contract

Info: PySH is Python-first. It is not POSIX /bin/sh, not a Bash clone, not a Zsh clone, and not a Fish clone. Legacy shells are migration and differential-test references; the documented PySH language contract is authoritative.

✓Interactive shell execution for external commands and PySH builtins
✓Pipelines, redirections, heredocs, chaining, history, completion, and foreground job control
✓Explicit .pysh script mode for PySH scripts
✓Unsupported shell constructs fail explicitly instead of being silently delegated to another shell

Who is PySH for?

✓System administrators replacing fragile shell-only automation with Python-backed workflows
✓DevOps engineers who want shell ergonomics plus Python modules, exceptions, testing, and packaging
✓Python developers who want an interactive Unix command workflow without leaving Python-first tooling
✓Teams that need explicit diagnostics, configuration, plugin contracts, and reproducible release evidence
✓Plugin authors targeting the stable PySH Plugin API 1.0

Core concepts

Interactive shell

Start pysh for an interactive shell with history, completion, multiline paste protection, command parsing, pipelines, redirections, and terminal-aware editing.

Python Command Execution Layer

Use #py for an interactive persistent Python layer, py <code> for one-line execution, and py { for multi-line Python blocks. Python state persists for the current PySH session.

Native PySH scripts

PySH can execute explicit .pyshscripts using the PySH language contract. Scripts are not treated as POSIX shell programs and PySH must not replace the operating system's /bin/sh.

Configuration

Safe declarative configuration lives in ~/.config/pysh/config.toml, with deterministic TOML drop-ins under ~/.config/pysh/conf.d/. Advanced programmable configuration remains available through trusted ~/.pyshrc.py, while legacy PySH rc files remain compatible.

Plugins

Trusted local plugins use Plugin API 1.0 and load only when explicitly enabled from ~/.pyshrc.py. A separate isolated-plugin runtime provides process separation and capability brokering, but it is not an operating-system sandbox.

Platform support

✓Tier 1: Debian-family Linux — Debian 13 / amd64 / CPython 3.13 is the reference evidence environment
✓Tier 1: FreeBSD family — FreeBSD 14.4 / amd64 / CPython 3.13, with FreeBSD 15 validation
✓Tier 2: RPM-family Linux — Fedora 43 native RPM install-and-run evidence
✓Runtime floor: CPython 3.13.0 or newer, with no upper minor-version bound

Next steps

Continue to Installation, then use the Quick Start. For configuration and extension work, continue with the Configuration and Plugin API 1.0 pages.