Plumbum: Shell Combinators
Contents
Menu
Expand
Light mode
Dark mode
Auto light/dark, in light mode
Auto light/dark, in dark mode
Skip to content
Plumbum: Shell Combinators
User Guide
Local Commands
Paths
The Local Object
Async Support
Remote
Utilities
Command-Line Interface (CLI)
TypedEnv
Colors
Reference
News
Change Log
Quick reference guide
API Reference
Package plumbum.cli
Package plumbum.commands
Package plumbum.machines
Package plumbum.path
Package plumbum.fs
Package plumbum.colors
Colorlib design
Back to top
View this page
Edit this page
Quick Links
Download
User Guide
API Reference
About
Tomer Filiba
Plumbum: Shell Combinators and More¶
Ever wished the compactness of shell scripts be put into a real programming language?<br>Say hello to Plumbum Shell Combinators. Plumbum (Latin for lead, which was used to create<br>pipes back in the day) is a small yet feature-rich library for shell script-like programs in Python.<br>The motto of the library is “Never write shell scripts again” , and thus it attempts to mimic<br>the shell syntax (shell combinators) where it makes sense, while keeping it all Pythonic<br>and cross-platform .
Apart from shell-like syntax and handy shortcuts,<br>the library provides local and remote command execution (over SSH),<br>local and remote file-system paths, easy working-directory and<br>environment manipulation, quick access to ANSI colors, and a programmatic<br>Command-Line Interface (CLI) application toolkit. Now let’s see some code!
News¶
2026.06.03 : Version 2.0.0 released with async, static typing, more pathlib API, no pywin32 dep, and much more!
2025.10.31 : Version 1.10.0 released with Python 3.9-3.14 support, and some small fixes.
2024.10.05 : Version 1.9.0 released with Python 3.8-3.13 support, and some small fixes.
2024.04.29 : Version 1.8.3 released with some small fixes, final version to support Python 3.6 and 3.7.
2023.05.30 : Version 1.8.2 released with a PyPI metadata fix, Python 3.12b1 testing, and a bit more typing.
See the full news archive.
Cheat Sheet¶
Basics¶
>>> from plumbum import local<br>>>> ls = local["ls"]<br>>>> ls<br>LocalCommand()<br>>>> ls()<br>'build.py\ndist\ndocs\nLICENSE\nplumbum\nREADME.rst\nsetup.py\ntests\ntodo.txt\n'<br>>>> notepad = local["c:\\windows\\notepad.exe"]<br>>>> notepad() # Notepad window pops up<br>'' # Notepad window is closed by user, command returns
Instead of writing xxx = local["xxx"] for every program you wish to use, you can<br>also import commands:
>>> from plumbum.cmd import grep, wc, cat, head<br>>>> grep<br>LocalCommand()
Or, use the local.cmd syntactic-sugar:
>>> local.cmd.ls<br>LocalCommand()<br>>>> local.cmd.ls()<br>'build.py\ndist\ndocs\nLICENSE\nplumbum\nREADME.rst\nsetup.py\ntests\ntodo.txt\n'
See Local Commands.
Piping¶
>>> chain = ls["-a"] | grep["-v", "\\.py"] | wc["-l"]<br>>>> print(chain)<br>/bin/ls -a | /bin/grep -v '\.py' | /usr/bin/wc -l<br>>>> chain()<br>'13\n'
See Pipelining.
Redirection¶
>>> ((cat "setup.py") | head["-n", 4])()<br>'#!/usr/bin/env python3\nimport os\n\ntry:\n'<br>>>> (ls["-a"] > "file.list")()<br>''<br>>>> (cat["file.list"] | wc["-l"])()<br>'17\n'
See Input/Output Redirection.
Working-directory manipulation¶
>>> local.cwd
>>> with local.cwd(local.cwd / "docs"):<br>... chain()<br>...<br>'15\n'
A more explicit, and thread-safe way of running a command in a different directory is using the .with_cwd() method:
.. code-block:: python
>>> ls_in_docs = local.cmd.ls.with_cwd("docs")<br>>>> ls_in_docs()<br>'api\nchangelog.rst\n_cheatsheet.rst\ncli.rst\ncolorlib.rst\n_color_list.html\ncolors.rst\nconf.py\nindex.rst\nlocal_commands.rst\nlocal_machine.rst\nmake.bat\nMakefile\n_news.rst\npaths.rst\nquickref.rst\nremote.rst\n_static\n_templates\ntyped_env.rst\nutils.rst\n'
See Paths and The Local Object.
Foreground and background execution¶
>>> from plumbum import FG, BG<br>>>> (ls["-a"] | grep["\\.py"]) & FG # The output is printed to stdout directly<br>build.py<br>.pydevproject<br>setup.py<br>>>> (ls["-a"] | grep["\\.py"]) & BG # The process runs "in the background"
See Background and Foreground.
Command nesting¶
>>> from plumbum.cmd import sudo<br>>>> print(sudo[ifconfig["-a"]])<br>/usr/bin/sudo /sbin/ifconfig -a<br>>>> (sudo[ifconfig["-a"]] | grep["-i", "loop"]) & FG<br>lo Link encap:Local Loopback<br>UP LOOPBACK RUNNING MTU:16436 Metric:1
See Command Nesting.
Remote commands (over SSH)¶
Supports openSSH-compatible clients,<br>PuTTY (on Windows)<br>and Paramiko (a pure-Python implementation of SSH2):
>>> from plumbum import SshMachine<br>>>> remote = SshMachine("somehost", user = "john", keyfile = "/path/to/idrsa")<br>>>> r_ls = remote["ls"]<br>>>> with remote.cwd("/lib"):<br>... (r_ls | grep["0.so.0"])()<br>...<br>'libusb-1.0.so.0\nlibusb-1.0.so.0.0.0\n'
See Remote.
CLI applications¶
import logging<br>from plumbum import cli
class MyCompiler(cli.Application):<br>verbose = cli.Flag(["-v", "--verbose"], help = "Enable verbose mode")<br>include_dirs = cli.SwitchAttr("-I", list = True, help = "Specify include directories")
@cli.switch("-loglevel", int)<br>def set_log_level(self,...