{"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":"en","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,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}