---
id: plumbum
version: "2.0.2"
license: MIT
license_treatment: permissive
maintenance: active
---

# plumbum — Plumbum: shell combinators library

License: permissive · Maintenance: active · Downloads: 6.5M/mo

## What it is and what it does

Plumbum is a Python library that brings shell script syntax and semantics into a real programming language. It lets you compose and execute shell commands using Python operators—piping with `|`, redirection with `<` and `>`, and nesting with bracket notation—while staying cross-platform and Pythonic. The library handles both local command execution and remote execution over SSH, manages working directories and environment variables programmatically, and includes a decorator-based CLI framework for building command-line applications.

Instead of writing separate shell scripts or laboriously constructing subprocess calls, you write Python code that reads like shell commands. It supports foreground and background execution, command composition, and file-system paths as first-class objects. The library also provides color and style utilities for terminal output.

Use it for:

- Build automation and task runners: chain compiler, linker, and build tool invocations with shell-like syntax.
- System administration scripts: execute local and remote commands over SSH with a unified Python API.
- CLI tool development: use the built-in Application framework to define flags, switches, and subcommands.
- Data pipeline orchestration: compose file operations, text processing, and command execution in a single script.
- Cross-platform scripting: write once, run on Windows, Linux, and macOS without rewriting shell logic.
- Log analysis and filtering: pipe commands like grep, awk, and sed equivalents directly in Python.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Plumbum lets you write shell-script-like programs in Python with piping, redirection, and command chaining syntax, plus local and remote command execution over SSH and a CLI application toolkit.

Yes. Plumbum is actively maintained, has no known vulnerabilities, installs with minimal friction, and carries a permissive MIT license. It is well-suited for anyone writing system administration scripts, build automation, or CLI tools who wants to avoid shell scripting or subprocess boilerplate. The library's maturity (first release 2012, currently 2.0.2) and broad Python version support (3.9–3.15) make it a reliable choice.

## Install

pip install plumbum
uv add plumbum
poetry add plumbum

## Installing plumbum

Before you install: Low install friction with a single lightweight runtime dependency (typing-extensions). Active maintenance with a recent release (23 days old) and steady repository activity.

License in practice: MIT license permits free use, modification, and distribution with minimal restrictions—suitable for both open-source and proprietary projects.

Quickstart:

from plumbum import local
from plumbum.cmd import ls, grep

# Run a single command
local.cmd.ls()

# Pipe commands together
chain = ls["-a"] | grep["-v", r"\.py"]
print(chain())

Requires Python 3.9 or later. Remote SSH execution requires an OpenSSH-compatible client, PuTTY (Windows), or Paramiko installed separately.

Verify before relying:

- Whether Paramiko is automatically installed or must be added separately for SSH support.
- Performance characteristics when chaining many commands or executing large batches of remote operations.
- Compatibility with non-POSIX shells on Windows beyond the documented PuTTY support.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 6.5M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

shell commands in python, python pipe and redirect, ssh command execution, cross-platform shell scripting, python cli framework, local and remote commands, command chaining library, shell-scripting, process-execution, cli-framework

[View on SkillFed](https://skillfed.io/packages/plumbum) · [View on PyPI](https://pypi.org/project/plumbum/)