Subprocess en Python: ejecutar comandos del terminal

El módulo subprocess en Python permite ejecutar programas externos y comandos del sistema desde un script. Es útil para automatizar herramientas, consultar versiones, comprimir archivos, ejecutar pruebas, invocar Git o conectar varias etapas de un flujo de trabajo.

La función recomendada para la mayoría de los casos es subprocess.run(). Ofrece control sobre argumentos, salida, errores, códigos de retorno, tiempo máximo y variables de entorno. Esta guía muestra cómo utilizarla de forma segura y portable.

Ejecutar el primer comando

import subprocess

result = subprocess.run(
    ["python", "--version"],
    check=True,
)

print(result.returncode)

Los argumentos se pasan como una lista. Cada elemento representa una parte del comando. Este formato evita problemas de espacios y reduce riesgos relacionados con la interpretación de texto por una shell.

La documentación oficial de subprocess recomienda run() para los casos que no necesitan una interacción avanzada con el proceso.

Capturar la salida estándar

import subprocess

result = subprocess.run(
    ["python", "--version"],
    capture_output=True,
    text=True,
    check=True,
)

print(result.stdout.strip())
print(result.stderr.strip())

capture_output=True conserva stdout y stderr. text=True convierte bytes en strings. Sin esa opción, el resultado se recibe como bytes.

La guía de strings en Python explica limpieza, codificación y transformación de texto.

Comprobar errores con check=True

Un comando puede terminar con un código diferente de cero. Sin check=True, Python devuelve el resultado y deja la validación al programa:

import subprocess

try:
    result = subprocess.run(
        ["python", "missing_script.py"],
        capture_output=True,
        text=True,
        check=True,
    )
except subprocess.CalledProcessError as error:
    print("El comando falló")
    print(error.returncode)
    print(error.stderr)

La guía de try y except en Python explica cómo capturar excepciones específicas y conservar el contexto.

Establecer un tiempo máximo

import subprocess

try:
    subprocess.run(
        ["python", "slow_task.py"],
        timeout=10,
        check=True,
    )
except subprocess.TimeoutExpired:
    print("El proceso superó el límite")

Un timeout evita que una automatización quede bloqueada indefinidamente. El valor correcto depende de la tarea y del entorno.

Evitar shell=True cuando no sea necesario

El argumento shell=True envía una cadena a la shell del sistema. Puede ser necesario para pipes, redirecciones o comandos internos, pero aumenta el riesgo cuando el texto contiene datos externos:

# Evita construir comandos con entrada del usuario
subprocess.run(
    f"tool --file {user_value}",
    shell=True,
)

Prefiere una lista:

subprocess.run(
    ["tool", "--file", user_value],
    check=True,
)

La sección de consideraciones de seguridad de subprocess explica la responsabilidad del desarrollador cuando utiliza una shell.

Ejecutar comandos diferentes según el sistema

import platform
import subprocess

system = platform.system()

if system == "Windows":
    command = ["cmd", "/c", "dir"]
else:
    command = ["ls", "-la"]

result = subprocess.run(
    command,
    capture_output=True,
    text=True,
    check=True,
)

print(result.stdout)

Cuando la tarea puede resolverse con la biblioteca estándar, una solución nativa suele ser más portable. Para archivos, consulta pathlib en Python y el módulo os.

Definir el directorio de trabajo

from pathlib import Path
import subprocess

project = Path.home() / "projects" / "demo"

result = subprocess.run(
    ["git", "status", "--short"],
    cwd=project,
    capture_output=True,
    text=True,
    check=True,
)

print(result.stdout)

cwd evita depender del directorio desde el que se inició el script.

Pasar variables de entorno

import os
import subprocess

environment = os.environ.copy()
environment["APP_MODE"] = "test"

subprocess.run(
    ["python", "app.py"],
    env=environment,
    check=True,
)

No reemplaces todo el entorno con un diccionario pequeño, porque el proceso puede necesitar PATH y otras variables. Tampoco incluyas secretos en mensajes de error o logs.

Enviar datos a stdin

import subprocess

result = subprocess.run(
    ["python", "processor.py"],
    input="first line\nsecond line\n",
    capture_output=True,
    text=True,
    check=True,
)

print(result.stdout)

input permite alimentar un proceso sin crear un archivo temporal.

Ejecutar una herramienta y convertir su salida

import json
import subprocess

result = subprocess.run(
    ["tool", "--format", "json"],
    capture_output=True,
    text=True,
    check=True,
)

data = json.loads(result.stdout)
print(data)

Valida siempre que la salida exista y tenga el formato esperado. Un proceso puede escribir mensajes de diagnóstico en stdout o stderr según su diseño.

Construir una función reutilizable

import subprocess


def run_command(command, *, cwd=None, timeout=30):
    try:
        return subprocess.run(
            command,
            cwd=cwd,
            timeout=timeout,
            capture_output=True,
            text=True,
            check=True,
        )
    except FileNotFoundError as error:
        raise RuntimeError(
            f"No se encontró el programa: {command[0]}"
        ) from error
    except subprocess.TimeoutExpired as error:
        raise RuntimeError(
            "El comando superó el tiempo máximo"
        ) from error
    except subprocess.CalledProcessError as error:
        message = error.stderr.strip() or "Sin detalles"
        raise RuntimeError(
            f"El comando falló: {message}"
        ) from error

La guía de funciones en Python ayuda a diseñar interfaces pequeñas y comprobables.

Crear una interfaz con argparse

Un script de automatización puede recibir parámetros y después ejecutar otra herramienta:

import argparse
import subprocess

parser = argparse.ArgumentParser()
parser.add_argument("filename")
args = parser.parse_args()

subprocess.run(
    ["python", "validator.py", args.filename],
    check=True,
)

La guía de argparse en Python explica opciones, tipos, ayuda y subcomandos.

Cuándo utilizar Popen

subprocess.Popen ofrece control de bajo nivel para procesos que deben continuar activos, intercambiar datos progresivamente o ejecutarse en paralelo. Para un comando que comienza, termina y devuelve un resultado, run() suele ser más claro.

Registrar sin exponer datos

import logging

logger = logging.getLogger(__name__)
logger.info("Ejecutando validación de archivos")

Registra la operación general, duración y código de salida. Evita tokens, contraseñas, argumentos privados o contenido completo de archivos.

La guía de automatización de tareas con Python muestra cómo combinar comandos, archivos, validación y registros.

Errores frecuentes

• Construir una cadena con entrada del usuario y shell=True.
• Ignorar el código de retorno.
• No definir timeout para procesos externos.
• Depender del directorio actual.
• Suponer que stdout siempre contiene datos válidos.
• Reemplazar todas las variables de entorno.
• Registrar argumentos sensibles.
• Usar comandos del sistema para tareas que pathlib resuelve mejor.

Conclusión

subprocess.run() permite integrar herramientas externas con un control claro sobre argumentos, salida, errores y tiempo máximo. Utiliza listas de argumentos, activa check=True, captura únicamente lo necesario y evita una shell cuando el comando pueda ejecutarse directamente. Con estas prácticas, los scripts de automatización resultan más seguros, portables y fáciles de diagnosticar.