Install & Compatibility
Where this runs
tested against v3.5.4 · 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.000s · 19.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.4s · import 0.000s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
subprocess
✓ import os, sys
if sys.version_info[0] < 3:
try:
import subprocess32 as subprocess
except ImportError:
import subprocess
else:
import subprocess
✗ import subprocess
On Python 2, directly importing `subprocess` (the built-in module) can lead to thread-safety issues and lacks modern features. The recommended pattern is to conditionally import `subprocess32` to leverage its fixes and features on Python 2, falling back to the built-in `subprocess` if `subprocess32` isn't available, and using the standard `subprocess` on Python 3.
This quickstart demonstrates the recommended import pattern and basic usage of the `subprocess.run()` function, which was backported from Python 3.5. It includes capturing output, handling errors with `check=True`, and setting a timeout. Note that `text=True` is an alias for `universal_newlines=True` within `subprocess32` for Python 2.
import os, sys
# Recommended import pattern for cross-version compatibility
if sys.version_info[0] < 3:
try:
import subprocess32 as subprocess
except ImportError:
print("Warning: subprocess32 not found, using native subprocess module.")
import subprocess
else:
import subprocess
try:
# Execute a simple command
result = subprocess.run(
['echo', 'Hello, subprocess32!'],
capture_output=True,
text=True, # In Python 2, this maps to universal_newlines=True
check=True,
timeout=5
)
print("STDOUT:", result.stdout.strip())
print("STDERR:", result.stderr.strip())
# Example with error
subprocess.run(['false'], check=True)
except subprocess.CalledProcessError as e:
print(f"Command failed with exit code {e.returncode}")
except subprocess.TimeoutExpired:
print("Command timed out")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Debug
Known issues
breakingThe `subprocess32` library is explicitly end-of-life (EOL) along with Python 2. This means no further development, bug fixes, or security updates are planned. Relying on it in new projects is strongly discouraged.fixMigrate applications from Python 2 to Python 3. Python 3's built-in `subprocess` module provides the same or superior functionality and thread safety.
affects: All versions (project-wide)
gotcha`subprocess32` is primarily designed for POSIX systems (Linux, macOS) and has not been tested or fully supported on Windows or other non-POSIX platforms. Attempts to install or use it on Windows may lead to compilation errors (e.g., missing `unistd.h`) or unexpected behavior.fixAvoid using `subprocess32` on Windows. For cross-platform Python 2 code, consider a conditional import that uses the native `subprocess` module on Windows, or use alternative process management libraries that explicitly support Windows.
affects: All versions
gotchaWhile `subprocess32` backports `timeout` support (from Python 3.3) and the `run()` API (from Python 3.5), other features and APIs are 'frozen at the 3.2 level'. This means `subprocess32` is not a complete, feature-for-feature replica of the latest Python 3 `subprocess` module.fixAlways consult Python 3.2 documentation for `subprocess` when using `subprocess32`, and explicitly check the `subprocess32` GitHub README for details on backported features like `run()` and `timeout`. Do not assume full parity with newer Python 3 versions.
affects: All versions
gotchaThe primary motivation for `subprocess32` was to address race conditions and improve thread-safety in Python 2.x's native `subprocess` module on POSIX systems, particularly in multi-threaded applications. Not using `subprocess32` (i.e., using the built-in `subprocess` on Python 2) can lead to unreliable behavior and crashes when processes are spawned in threaded contexts.fixAlways use `subprocess32` (via the conditional import pattern) when running Python 2.x code that spawns subprocesses, especially in threaded environments. For new development, migrate to Python 3.
affects: Python 2.x (native subprocess module)
Errors
Common errors & fixes
AttributeError: 'module' object has no attribute 'run'
The 'run' function for `subprocess` was introduced in Python 3.5 and is not available in the standard `subprocess` module in Python 2.
fixInstall `subprocess32` (`pip install subprocess32`) and modify your code to use `subprocess32.run(...)` or import it as `import subprocess32 as subprocess` and then use `subprocess.run(...)`.
ModuleNotFoundError: No module named 'subprocess32'
The `subprocess32` library has not been installed in the active Python 2 environment.
fixInstall the library using pip: `pip install subprocess32`.
ImportError: cannot import name TimeoutExpired
The `TimeoutExpired` exception class is a Python 3.3+ feature and is not available in the standard Python 2 `subprocess` module.
fixEnsure `subprocess32` is installed (`pip install subprocess32`) and import `TimeoutExpired` directly from it: `from subprocess32 import TimeoutExpired`.
Upgrade
Version history
3.5.4latest on PyPI · released May 20, 2019
Audit
Dependencies
No dependency data recorded yet.