explaingit

amoffat/sh

★ 7,235PythonAudience · developerComplexity · 2/5Setup · easy

TLDR

A Python library that turns any command-line program into a callable Python function, replacing verbose subprocess calls with simple, readable one-liners.

Mindmap

mindmap
  root((sh))
    What it does
      Shell as Python functions
      Replaces subprocess
      Unix only
    Features
      Import any command
      Pipe commands
      Streaming output
    Use Cases
      System automation
      Deployment scripts
      Data pipelines
    Compatibility
      Python 3.8 to 3.12
      PyPy supported
    Setup
      pip install sh
      Linux and macOS only
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Things people build with this

USE CASE 1

Replace complex subprocess calls in a Python script by importing and calling shell commands as regular Python functions.

USE CASE 2

Automate system administration tasks in Python by chaining CLI tools like git, rsync, and docker naturally.

USE CASE 3

Build a deployment script that runs multiple shell commands in sequence and captures their output as Python strings.

Tech stack

PythonPyPy

Getting it running

Difficulty · easy Time to first run · 5min

Does not support Windows, requires a Unix-like operating system such as Linux or macOS.

In plain English

sh is a Python library that lets you run any command-line program as if it were an ordinary Python function. Instead of writing subprocess calls with long argument lists, you import the program by name and call it directly. For example, to run ifconfig on the eth0 interface, you write from sh import ifconfig and then call ifconfig("eth0"). The output comes back as a string you can use in your Python code. The library is a replacement for Python's built-in subprocess module, which handles running external programs but requires more boilerplate to use. sh aims to make that same task feel natural and concise. It works on Linux, macOS, and other Unix-like operating systems, but it does not support Windows because it relies on Unix system calls internally. Compatible Python versions are 3.8 through 3.12 and also PyPy. Installing it takes one pip command. The full documentation with usage examples and advanced options is hosted at sh.readthedocs.io. The README itself is brief and mostly covers installation and how to run the test suite for developers who want to contribute. The project is actively maintained, currently at version 2, and there is a migration guide for users upgrading from the earlier 1.x version. Tests run inside Docker containers against all supported Python versions.

Copy-paste prompts

Prompt 1
Use Python's sh library to write a script that runs git log and parses the commit messages from its output.
Prompt 2
Show me how to pipe shell commands together using the sh library in Python, like cat piped into grep.
Prompt 3
Use sh to run a long-running process in Python and stream its stdout output line by line in real time.
Prompt 4
Write a Python script using sh that runs multiple shell commands and collects all their results.
Prompt 5
How do I pass environment variables and a custom working directory to a command run with the sh library?
Open on GitHub → Explain another repo

← amoffat on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.