{"id":2297,"library":"subprocess-tee","title":"subprocess-tee","description":"This package provides a Pythonic alternative to `subprocess.run` that captures the output of a child process while simultaneously printing it to the console in real-time, mimicking the behavior of the `tee` command. It is designed for long-running processes where instant feedback is desirable. The current version is 0.4.2 and it maintains a stable release cadence.","status":"active","version":"0.4.2","language":"python","source_language":"en","source_url":"https://github.com/pycontribs/subprocess-tee","tags":["subprocess","tee","real-time","output","utility","process-management"],"install":[{"cmd":"pip install subprocess-tee","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"The primary function `run` replaces `subprocess.run`.","symbol":"run","correct":"from subprocess_tee import run"}],"quickstart":{"code":"from subprocess_tee import run\n\n# Basic usage: Command output is printed to console and captured\nresult = run([\"echo\", \"Hello, subprocess-tee!\"])\nprint(f\"Captured stdout: {result.stdout.strip()}\")\nprint(f\"Return code: {result.returncode}\")\n\n# To explicitly disable tee functionality (e.g., just capture output):\nresult_no_tee = run([\"python\", \"-c\", \"import time; print('start'); time.sleep(0.1); print('end')\"], tee=False, capture_output=True, text=True)\nprint(f\"Captured stdout without tee: {result_no_tee.stdout.strip()}\")\n\n# Example with error and checking return code:\ntry:\n    run([\"false\"], check=True, capture_output=True, text=True)\nexcept Exception as e:\n    print(f\"Command failed as expected: {e}\")","lang":"python","description":"The `run` function is designed to be a drop-in replacement for `subprocess.run`. By default, it prints output to `sys.stdout` and `sys.stderr` while also capturing it. Use `tee=False` to disable real-time printing if only output capture is needed. The `check=True` argument will raise a `CalledProcessError` on non-zero exit codes, similar to `subprocess.run`."},"warnings":[{"fix":"Be aware that `stdout` and `stderr` attributes of the `CompletedProcess` object will contain strings, not bytes. If binary output is strictly required, `subprocess-tee` might not be the most suitable tool or may require careful handling of encoding.","message":"The `subprocess-tee.run` function implies `text=True` (or `universal_newlines=True`) by default. This means output is treated as text (decoded using default encoding, usually UTF-8), which differs from `subprocess.run` where `text=False` (binary output) is the default unless specified.","severity":"gotcha","affected_versions":"All versions"},{"fix":"On Windows, consider using `shell=True` with caution (see next warning) or ensure commands are simple strings. Test extensively for complex argument scenarios on Windows environments.","message":"There are known open issues on Windows related to incorrect argument list conversion and lack of support for multiple arguments when not using `shell=True`. This can lead to commands not executing as expected.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If child processes are expected to produce non-UTF-8 output, ensure they are configured to use UTF-8 or be prepared to handle potential encoding issues programmatically. There is currently no direct `encoding` parameter in `subprocess-tee.run` to override the default text handling.","message":"The library may not correctly handle non-UTF-8 characters in the output of child processes due to an open bug. This could lead to `UnicodeDecodeError` or garbled output.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Avoid `shell=True` when executing commands with external or untrusted input. Prefer passing commands as a list of arguments (`['command', 'arg1', 'arg2']`) to bypass the shell.","message":"Using `shell=True` with user-provided input in commands can introduce security vulnerabilities (e.g., command injection). While this is a general `subprocess` module concern, it applies equally to `subprocess-tee`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'0.4.2':55 'altern':9 'behavior':33 'cadenc':62 'captur':13 'child':18 'command':37 'consol':26 'current':52 'design':40 'desir':50 'feedback':48 'instant':47 'long':43 'long-run':42 'maintain':58 'manag':72 'mimick':31 'output':15,68 'packag':5 'print':22 'process':19,45,71 'process-manag':70 'provid':6 'python':8 'real':29,66 'real-tim':28,65 'releas':61 'run':44 'simultan':21 'stabl':60 'subprocess':2,63 'subprocess-te':1 'subprocess.run':11 'tee':3,36,64 'time':30,67 'util':69 'version':53","created_at":"2026-04-09T18:51:56.966013+00:00","updated_at":"2026-04-16T22:31:02.379660+00:00","problems":[{"fix":"Use `import subprocess_tee` in your Python code.","cause":"The package is installed as `subprocess-tee` using a hyphen, but the Python module name uses an underscore (`subprocess_tee`).","error":"ModuleNotFoundError: No module named 'subprocess_tee'"},{"fix":"Handle the exception using a `try...except subprocess_tee.CalledProcessError` block, or explicitly pass `check=False` to `subprocess_tee.run()` if you intend to ignore non-zero exit codes.","cause":"The executed command returned a non-zero exit status, and the `check=True` parameter (which is the default in `subprocess_tee.run()`) caused an exception to be raised.","error":"subprocess_tee.CalledProcessError: Command '['ls', 'nonexistent_file']' returned non-zero exit status 1."},{"fix":"Ensure consistency: if `text=True` (default for `subprocess_tee`), `result.stdout` is a string. If `text=False`, `result.stdout` is bytes and needs decoding (e.g., `result.stdout.decode('utf-8')`) before string operations, or ensure you are passing bytes where expected.","cause":"The output (`stdout` or `stderr`) from the child process is in a different type (bytes or string) than expected, often due to the `text` or `universal_newlines` argument in `subprocess_tee.run()`.","error":"TypeError: a bytes-like object is required, not 'str'"},{"fix":"Use the `input` keyword argument, passing the input as a string (if `text=True`) or bytes (if `text=False`): `subprocess_tee.run(command, input='my input data', text=True)`.","cause":"The user wants to provide input to the child process via its standard input, but is unsure how to pass it using `subprocess_tee.run()`.","error":"subprocess-tee stdin input"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.4.2","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/pycontribs/subprocess-tee","docs":"https://subprocess-tee.readthedocs.io","changelog":"https://github.com/pycontribs/subprocess-tee/releases","pypi":"https://pypi.org/project/subprocess-tee/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}