Plumbum: Shell Combinators Library

1.10.0 · active · verified Thu Apr 09

Plumbum is a Python library for writing shell scripts in a Pythonic manner. It allows you to invoke external commands, chain them using pipes, redirect I/O, and build command-line applications programmatically. The current version is 1.10.0, and it maintains an active release cadence with minor versions and patch releases addressing bug fixes and Python version support.

Warnings

breaking Plumbum has dropped support for older Python versions in recent releases. Version 1.10.0 requires Python >=3.9. Version 1.9.0 dropped support for Python <3.8, and v1.8.0 dropped Python 2.7 and 3.5.
Fix: Ensure your Python environment is at least 3.9 for `plumbum` v1.10.0+. Check the specific `plumbum` version's `requires_python` metadata.
gotcha Complex or long-running `plumbum` pipelines can occasionally stall due to buffering or underlying OS pipe behavior. While fixes have been applied (e.g., v1.8.3), it remains a potential issue.
Fix: Consult the official documentation on 'Stalling Pipelines' for advanced techniques such as explicit `wait()` calls, adjusting `iter_lines(buffer_size=...)`, or using explicit redirection strategies for better control over I/O.
gotcha Prior to v1.10.0, `plumbum.cli` applications might have incorrectly handled `False` values for flags, treating them as if the flag was not provided at all.
Fix: Upgrade to `plumbum` v1.10.0 or later to ensure `False` flag values are respected. Review your CLI application logic if relying on explicit `False` inputs.
breaking The packaging backend for `plumbum` moved from setuptools to Hatchling in v1.8.1. While this should be transparent for most users, third-party packaging or specific build systems might require adaptation.
Fix: If experiencing build issues or difficulties integrating `plumbum` v1.8.1+ into a custom build pipeline, verify compatibility with Hatchling-based projects and update your build tooling as necessary.

Install

pip install plumbum Install stable version

Imports

cmd
```
from plumbum import cmd
```
Accesses external commands via attribute lookup (e.g., cmd.ls, cmd.grep).
local
```
from plumbum import local
```
Represents the local machine context for path and environment operations.
SshMachine
```
from plumbum import SshMachine
```
For connecting to and executing commands on remote SSH machines.
cli
```
from plumbum import cli
```
For building declarative command-line interfaces.

Quickstart

This quickstart demonstrates how to run external commands, chain them with pipes, access local machine context (like current working directory), and execute commands within specific directories using `plumbum`.

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

# Run a simple command and capture output
output = ls("-a")
print(f"ls -a output:\n{output}")

# Pipe commands together
pipe_output = (ls["-a"] | grep["-i", "py"])()
print(f"ls -a | grep -i py output:\n{pipe_output}")

# Access local machine paths and environment
print(f"Current directory: {local.cwd}")
print(f"User home: {local.home}")

# Execute a command in a specific directory
with local.cwd(local.tempdir):
    temp_dir_files = ls()
    print(f"Files in temporary directory: {temp_dir_files}")

view raw JSON →