subprocess e Interoperabilidad con Shell

subprocess ejecuta binarios externos desde Python con argumentos controlados, tiempos de espera y salida capturada. Evita shell=True a menos que aceptes el riesgo de inyección y la complejidad de las comillas.

Receta

import subprocess
 
proc = subprocess.run(
    ["git", "rev-parse", "HEAD"],
    check=True,
    capture_output=True,
    text=True,
    timeout=30,
)
print(proc.stdout.strip())

Cuándo usar esto:

• Git, rsync, tar, ffmpeg y otras herramientas CLI maduras
• Scripts de shell heredados que estás envolviendo incrementalmente
• Capturar stdout para analizar en Python
• Limitar el tiempo de ejecución de comandos largos para evitar trabajos cron bloqueados

Ejemplo Funcional

Ejecuta un comando con tiempo de espera, mapea errores a códigos de salida, transmite grandes volúmenes de salida línea por línea.

import logging
import subprocess
from collections.abc import Sequence
 
log = logging.getLogger(__name__)
 
def run_command(cmd: Sequence[str], timeout: float = 60) -> subprocess.CompletedProcess[str]:
    log.info("ejecutando %s", list(cmd))
    try:
        return subprocess.run(
            cmd,
            check=True,
            capture_output=True,
            text=True,
            timeout=timeout,
        )
    except subprocess.TimeoutExpired as exc:
        log.error("tiempo de espera agotado después de %ss: %s", timeout, cmd)
        raise
    except subprocess.CalledProcessError as exc:
        log.error("salida con código %s stderr=%s", exc.returncode, exc.stderr.strip())
        raise
 
def stream_lines(cmd: Sequence[str]) -> int:
    with subprocess.Popen(cmd, stdout=subprocess.PIPE, text=True) as proc:
        assert proc.stdout is not None
        for line in proc.stdout:
            print(line.rstrip())
        return proc.wait()
 
if __name__ == "__main__":
    result = run_command(["python3", "--version"])
    print(result.stdout)

Lo que esto demuestra:

• Secuencia de argumentos, no una cadena de shell: sin superficie de inyección
• check=True lanza CalledProcessError con el código de retorno y stderr
• Popen transmite stdout sin almacenar en búfer toda la salida en memoria

Análisis Profundo

Elección de API

Riesgo de shell=True

• La entrada del usuario en la cadena de comandos permite la inyección de shell
• Prefiere argv de lista; si se requiere shell, usa shlex.quote en segmentos de usuario

Notas de Python

import shlex
 
user_file = "report; rm -rf /"
# MAL: subprocess.run(f"cat {user_file}", shell=True)
subprocess.run(["cat", user_file], check=True)

Errores Comunes

• shell=True con variables - error clásico de inyección. Solución: lista argv o shlex.split solo en scripts confiables.
• Sin tiempo de espera - trabajos cron zombis para siempre. Solución: siempre establece timeout proporcional al tiempo de ejecución esperado.
• Capturar stdout enorme - explosión de memoria. Solución: transmitir con Popen o redirigir a un archivo temporal.
• Ignorar stderr - contexto de fallo oculto. Solución: registrar stderr en caso de salida distinta de cero.
• Codificación en modo texto - las herramientas binarias fallan. Solución: text=False y decodificar explícitamente cuando sea necesario.

Alternativas

Preguntas Frecuentes

Relacionado

• Conceptos Básicos de Scripting - puntos de entrada CLI
• SSH y Ejecución Remota - comandos remotos
• Scripts Robustos - manejo de errores
• Análisis de Registros y Texto - analizar la salida del comando
• Mejores Prácticas de Scripting de Sistemas - ejecución segura

Versiones de la pila: Esta página fue escrita para Python 3.14.0 (estable 3.14, mantenimiento 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+ y uv 0.6+.