{"id":2192,"library":"plumbum","title":"Plumbum: Shell Combinators Library","description":"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.","status":"active","version":"1.10.0","language":"en","source_language":"en","source_url":"https://github.com/tomerfiliba/plumbum","tags":["shell","automation","cli","system","process"],"install":[{"cmd":"pip install plumbum","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for some Windows-specific functionality, automatically installed on Windows platforms.","package":"pywin32","optional":true}],"imports":[{"note":"Accesses external commands via attribute lookup (e.g., cmd.ls, cmd.grep).","symbol":"cmd","correct":"from plumbum import cmd"},{"note":"Represents the local machine context for path and environment operations.","symbol":"local","correct":"from plumbum import local"},{"note":"For connecting to and executing commands on remote SSH machines.","symbol":"SshMachine","correct":"from plumbum import SshMachine"},{"note":"For building declarative command-line interfaces.","symbol":"cli","correct":"from plumbum import cli"}],"quickstart":{"code":"from plumbum import cmd\nfrom plumbum.cmd import ls, grep\nfrom plumbum import local\n\n# Run a simple command and capture output\noutput = ls(\"-a\")\nprint(f\"ls -a output:\\n{output}\")\n\n# Pipe commands together\npipe_output = (ls[\"-a\"] | grep[\"-i\", \"py\"])()\nprint(f\"ls -a | grep -i py output:\\n{pipe_output}\")\n\n# Access local machine paths and environment\nprint(f\"Current directory: {local.cwd}\")\nprint(f\"User home: {local.home}\")\n\n# Execute a command in a specific directory\nwith local.cwd(local.tempdir):\n    temp_dir_files = ls()\n    print(f\"Files in temporary directory: {temp_dir_files}\")","lang":"python","description":"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`."},"warnings":[{"fix":"Ensure your Python environment is at least 3.9 for `plumbum` v1.10.0+. Check the specific `plumbum` version's `requires_python` metadata.","message":"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.","severity":"breaking","affected_versions":"1.8.0, 1.9.0, 1.10.0 and above"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.8.3 (and potentially later for complex scenarios)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.10.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"1.8.1 and above"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}