Install & Compatibility
Where this runs
tested against v0.1.8 · 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.910 runs
installs and imports cleanly · install 0.0s · import 0.038s · 17.9MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.5s · import 0.036s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
run
✓ from sarge import run
Primary function to execute shell commands and pipelines.
capture_stdout
✓ from sarge import capture_stdout
Convenience function to run a command and capture its standard output.
Pipeline
✓ from sarge import Pipeline
Represents a sequence of commands, returned by `run()` and similar functions.
Command
✓ from sarge import Command
Represents a single command within a pipeline.
Capture
✓ from sarge import Capture
Object used to read captured stdout/stderr streams.
shell_format
✓ from sarge import shell_format
Utility for safely formatting shell commands to prevent injection attacks.
This quickstart demonstrates how to use `sarge.run` to execute single commands and pipelines, capture output, and inspect return codes. The `Capture()` object is used to collect stdout for later access.
import sarge
# Run a simple command and get its output
p = sarge.run('echo "Hello from Sarge!"', stdout=sarge.Capture())
print(p.stdout.text.strip())
# Run a command pipeline
p = sarge.run('ls -l | grep .py', stdout=sarge.Capture())
print(p.stdout.text)
# Check return codes
p = sarge.run('false || echo success', stdout=sarge.Capture())
print(f"Return code: {p.returncode}")
print(f"Output: {p.stdout.text.strip()}")
Debug
Known issues
gotchaThe `async` keyword argument was renamed to `async_` in version 0.1.5+ because `async` became a reserved keyword in Python 3.7. Using `async` in newer Python versions will result in a `SyntaxError`.fixAlways use `async_` instead of `async` when specifying asynchronous execution for commands, especially in Python 3.7 and newer.
affects: 0.1.5+
gotchaSarge's asynchronous features (commands specified with `&` in a pipeline) are considered experimental and their API might be subject to change in future minor releases.fixWhile these features are available, be aware that code relying heavily on asynchronous command execution might require adjustments with future updates. Stick to synchronous execution for maximum stability if not critical.
affects: All versions
gotchaSarge communicates data (input to commands, captured output) as bytes, not text, and defaults to UTF-8 encoding for text-to-bytes conversion. This differs from Python 2.x's default ASCII encoding and can lead to `UnicodeEncodeError` or `UnicodeDecodeError` if not handled correctly.fixEnsure all input data is properly encoded to bytes (e.g., `text.encode('utf-8')`) and decoded from bytes (e.g., `p.stdout.text` will decode with UTF-8 by default in sarge). For Python 2.x, use `from __future__ import unicode_literals` and byte literals (e.g., `b'foo'`) for cross-version compatibility. affects: All versions (especially Python 2.x users)
gotchaSarge, like `subprocess`, cannot directly interact with programs that require a controlling terminal (e.g., `ftp`, `ssh` for password prompts). It operates on `stdin`, `stdout`, and `stderr` streams, not pseudo-terminals.fixFor programs requiring direct terminal interaction or pseudo-terminal emulation, consider using libraries like `pexpect` instead of `sarge`.
affects: All versions
Errors
Common errors & fixes
SyntaxError: invalid syntax (for 'async')
Using `async` as a keyword argument in `sarge.run()` or similar functions in Python 3.7+ environments, where `async` became a reserved keyword.
fixChange the keyword argument from `async=True` to `async_=True`.
UnicodeEncodeError: 'ascii' codec can't encode character...
Attempting to pass Unicode strings containing non-ASCII characters to a child process on Python 2.x, especially when `sarge`'s environment handling expects native strings on Windows, without proper encoding.
fixExplicitly encode Unicode strings to bytes using UTF-8 before passing them as input, or ensure environment variables on Python 2.x Windows are native `str` types. Sarge itself will use UTF-8 for text-to-bytes conversion internally for most inputs.
CommandNotFound: [Errno 2] No such file or directory: 'some_command'
The shell command specified in `sarge.run()` or similar functions cannot be found in the system's PATH, or on Windows, the command or its associated executable cannot be resolved.
fixVerify that the command is correctly spelled and executable, and that its directory is included in the system's PATH environment variable. On Windows, ensure that associated executables (e.g., Python for `.py` scripts) are properly registered or in PATH.
Upgrade
Version history
0.1.8latest on PyPI · released Jan 20, 2026
Audit
Dependencies
No dependency data recorded yet.