Install & Compatibility
Where this runs
tested against v2.0.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.206s · 19.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.9s · import 0.186s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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}")
Debug
Known issues
breakingPlumbum 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.fixEnsure your Python environment is at least 3.9 for `plumbum` v1.10.0+. Check the specific `plumbum` version's `requires_python` metadata.
affects: 1.8.0, 1.9.0, 1.10.0 and above
gotchaComplex 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.fixConsult 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.
affects: <1.8.3 (and potentially later for complex scenarios)
gotchaPrior 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.fixUpgrade 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.
affects: <1.10.0
breakingThe 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.fixIf 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.
affects: 1.8.1 and above
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'plumbum'
The 'plumbum' library is not installed in the current Python environment.
fixRun `pip install plumbum` in your terminal to install the library.
plumbum.commands.CommandNotFound
Plumbum could not locate the specified external command in the system's PATH environment variable.
fixEnsure the command is installed and its executable directory is correctly added to your system's PATH. Alternatively, provide the full path to the executable or use `local.get('command_name', '/full/path/to/command')` to include fallbacks. plumbum.commands.processes.ProcessExecutionError
A command executed by Plumbum returned a non-zero exit code, which by default indicates an error condition.
fixTo handle or ignore specific exit codes, pass the `retcode` argument to the `.run()` method; for example, `command.run(retcode=None)` to ignore all exit codes, or `command.run(retcode=(0, 1))` to accept exit codes 0 and 1 as successful.
AttributeError: 'str' object has no attribute 'run'
You are attempting to call the `.run()` method on a standard Python string, not a plumbum command object.
fixEnsure that the variable you are calling `.run()` on is a plumbum command object, created using `local['command_name']` or `from plumbum.cmd import command_name`.
Upgrade
Version history
2.0.2latest on PyPI · released Jul 22, 2026
Audit
Dependencies
pywin32optionalRequired for some Windows-specific functionality, automatically installed on Windows platforms.