amoffat/sh: calling Unix programs as Python functions
Python process launching
At a glance
- What is it?
- sh replaces subprocess with attribute access: from sh import git, then git("status", "--short"). It runs on Unix only, requires Python 3.10 or newer, and installs with pip install sh.
- Who is it for?
- Adopt sh if your code runs on Linux, macOS or a BSD and you want command output as a Python object without writing Popen plumbing by hand. Do not adopt it for Windows targets, for air-gapped builds that cannot pull a wheel from PyPI, or for pipelines where you need to inspect raw process state that sh's wrappers abstract away.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 113 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- amoffat/sh7,248 ★ · +6
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| amoffat/sh | 7.2k | 7.2k |
6 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The problem sh solves, and who it is actually for
Python's subprocess module makes you assemble a list of arguments, pick a capture mode, decode bytes, and check returncode yourself. sh collapses that into attribute access. The README's opening example is the whole pitch:
from sh import git
print(git("status", "--short"))Importing the module name git produces a callable that resolves to the git binary on PATH. The README is explicit about what this is not: "sh is not a collection of system commands implemented in Python." There is no bundled git, no reimplemented ls. Every call goes out to a real executable, so anything on the host that a shell could run, sh can run.
The audience follows from that. The package classifiers list Intended Audience :: Developers and Intended Audience :: System Administrators. This is for people writing deployment scripts, build tooling, CI helpers, or admin automation in Python who are tired of stringing together subprocess.run calls. It is a worse fit for application code that needs to be portable across operating systems, because the README states plainly that sh "relies on various Unix system calls and only works on Unix-like operating systems - Linux, macOS, BSDs etc. Specifically, Windows is not supported."
How the function-call mechanism maps onto a real process
The name you import becomes an object whose __call__ spawns a process. The call blocks until the program exits, and the return value is a wrapper around the captured stdout, which is why print(git(...)) works directly.
Failures are the part worth reading the docs for. When a program exits non-zero, sh raises rather than returning a status code. That exception type is ErrorReturnCode. The design intent is that a failed command interrupts your Python control flow the way an exception normally would, instead of being silently ignored the way a bare Popen call can be.
The execution model is also why the Unix restriction is not an oversight to be patched later. Process groups, signals, and the file-descriptor handling sh relies on are POSIX behaviours. A Windows port would be a different library wearing the same name.
Installing sh and running a first command
Installation is a single pip command, which is the one the README gives under its Installation heading. There is no compiler step and no system package to install first, assuming you already have Python in the supported range:
pip install shAfter that, importing a program name is enough. The module resolves the executable from PATH at call time, so the binary has to exist on the machine where the code runs. The README's own example is the shortest way to see the result:
from sh import git
print(git("status", "--short"))Run that inside a git repository and it prints the short status. Run it outside one and git exits non-zero, which means sh raises ErrorReturnCode instead of printing anything. That distinction is the first thing to internalise: a missing binary or a failed command surfaces as a Python exception, not as an empty string.
If you are contributing rather than consuming, the repository layout is conventional for a modern Python project. Source lives under src/sh, tests under tests, and the Makefile drives the suite through tox. The README gives make test for the full run on all supported interpreters and make test='FunctionalTests.test_background' test_one for a single test. Documentation is built separately with cd docs followed by make html, which writes into docs/build/html.
Where sh stops being the right tool
The Unix-only constraint is the first hard boundary, and it is not negotiable. If any part of your deployment matrix includes Windows, you need a different approach for that leg. The README does not document a compatibility shim.
The second limitation is subtler. Because importing a name resolves a binary rather than a Python module, tooling that inspects imports statically will not see the dependency. A linter cannot tell you that your code needs git installed, and a container image built from your requirements file will not include it. The failure appears at runtime, as an exception, on the machine that lacks the binary. That is a real operational cost for teams used to dependency manifests being complete.
The third is that the library's convenience is also its opacity. Everything subprocess exposes about process state, sh wraps. When you need to reason about file descriptors, process groups, or partial reads from a long-running child, you are working against the abstraction rather than with it. The README does not document rollback or recovery semantics for partially consumed output, so if that matters to your use case, read the full documentation at sh.readthedocs.io before designing around it.
How sh differs from calling subprocess directly
The obvious alternative is the standard library's subprocess module, which sh is explicitly positioned against. The difference in approach is where the ceremony lives. With subprocess you write the argv list, choose check=True or inspect returncode, set text=True or decode bytes, and handle the output object yourself. Every one of those decisions is visible in your code, which is verbose but also means nothing is hidden.
sh moves all of that into the callable. You get shorter call sites and exception-based failure by default, at the cost of implicit behaviour: the argument-to-argv mapping, the environment inheritance, and the output wrapping all happen without you writing them down. For a script that runs four commands, that trade is easy. For a long-lived service that spawns processes under load and needs to tune buffering and signal handling, the explicit subprocess version is easier to reason about, and the extra lines buy you visibility you will want during an incident.
A second alternative worth naming is writing the pipeline in a shell script and calling it once from Python. That keeps the shell semantics you already know and reduces the Python surface to a single subprocess call, but it moves logic out of your testable Python code and into a file that is harder to unit test. sh sits between the two: shell-like ergonomics with Python control flow.
Maintenance, releases and what the MIT licence means here
The project is not archived, and the last push to the develop branch was on 2026-07-25. The most recent release, 2.4.0, carries the same date, following 2.3.0 on 2026-06-09 and 2.2.6 on 2026-06-08. The pyproject.toml declares version 2.4.0, requires-python >=3.10,<4.0, and classifiers for CPython 3.10 through 3.14 plus PyPy. Development Status is listed as 5 - Production/Stable.
Upgrade cost is low by construction. The package is pure Python, distributed as a wheel built by hatchling from src/sh, so there is no ABI to track and no compiled extension to rebuild. The practical constraint is the interpreter floor: the 3.10 minimum is a real gate, and the <4.0 ceiling means a future Python 4 would need a new release before you could move.
The licence is MIT, declared both in the classifier list and in pyproject.toml as license = {text = "MIT"}. That is permissive: you can use sh in commercial and closed-source software, and you are not obliged to publish your own code. It does not remove the obligation to comply with the licences of the programs you invoke through it, which sh has nothing to do with. This is a description of the declared licence text, not legal advice; read LICENSE.txt in the repository if the distinction matters to your organisation.
Editorial conclusion
Adopt sh if your code runs on Linux, macOS or a BSD and you want command output as a Python object without writing Popen plumbing by hand. Do not adopt it for Windows targets, for air-gapped builds that cannot pull a wheel from PyPI, or for pipelines where you need to inspect raw process state that sh's wrappers abstract away. Before committing, verify three things in your own environment: that the interpreter is between 3.10 and 3.14, that every command you plan to call exists on the target host, and that your error handling accounts for ErrorReturnCode rather than a plain non-zero return value.
Frequently asked questions
What does sh do that subprocess does not?
It lets you import a program name and call it like a function, so git("status", "--short") spawns git with those arguments and returns the captured output. subprocess requires you to build the argument list, choose a capture mode and check the return code yourself.
Does sh work on Windows?
No. The README states that sh relies on Unix system calls and only works on Unix-like operating systems such as Linux, macOS and the BSDs, and that Windows is specifically not supported.
What is ErrorReturnCode in sh?
It is the exception raised when a program called through sh exits with a non-zero status. Instead of returning a status code for you to check, sh interrupts your Python control flow, so a failed command has to be handled as an exception.
Which Python versions does sh support?
The README lists Python 3.10 through 3.14 and PyPy, and pyproject.toml sets requires-python to >=3.10,<4.0 with classifiers for CPython 3.10 to 3.14.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/amoffat-sh)Star history chart for your README
[](https://hysenlabs.com/projects/amoffat-sh)Was this useful?