`subprocess` — Gestión de subprocesos¶

Código fuente: Lib/subprocess.py

El módulo subprocess permite lanzar nuevos procesos, conectarse a sus pipes de entrada/salida/error y obtener sus códigos de resultado. Este módulo está destinado a reemplazar múltiples módulos y funciones previamente existentes:

os.system
os.spawn*

Se puede obtener información sobre cómo utilizar el módulo subprocess para reemplazar estos módulos y funciones en las siguientes secciones.

Ver también

PEP 324 – PEP de proposición del módulo subprocess

Uso del módulo `subprocess`¶

La opción recomendada para invocar subprocesos es utilizar la función run() para todos los casos al alcance de ésta. Para usos más avanzados, se puede utilizar la interfaz de más bajo nivel Popen.

La función run() se añadió en Python 3.5; si necesita mantener la compatibilidad con versiones anteriores, consulte la sección Antigua API de alto nivel.

subprocess.run(args, *, stdin=None, input=None, stdout=None, stderr=None, capture_output=False, shell=False, cwd=None, timeout=None, check=False, encoding=None, errors=None, text=None, env=None, universal_newlines=None, **other_popen_kwargs)¶

Ejecuta la orden descrita por args. Espera a que termine y retorna una instancia de CompletedProcess.

Los argumentos mostrados en la definición superior son sólo los más comunes; que se describen posteriormente en Argumentos frecuentemente empleados (de ahí el uso de la notación por clave en la signatura abreviada). La signatura completa de la función es a grandes rasgos la misma que la del constructor de Popen; la mayoría de los argumentos de esta función se pasan a esa interfaz (no es el caso de timeout, input, check ni capture_output).

Si capture_output es verdadero, se capturarán stdout y stderr. En tal caso, el objeto Popen interno se crea automáticamente con stdout=PIPE y stderr=PIPE. No se pueden proporcionar los argumentos stdout y stderr a la vez que capture_output. Si se desea capturar y combinar los dos flujos, se ha de usar stdout=PIPE y stderr=STDOUT en lugar de capture_output.

El argumento timeout se pasa a Popen.communicate(). Si vence el plazo de ejecución, se matará el proceso hijo y se le esperará. Se relanzará la excepción TimeoutExpired cuando finalice el proceso hijo.

Se pasará el argumento input a Popen.communicate() y de ahí, a la entrada estándar del subproceso. Si se usa, debe ser una secuencia de bytes o una cadena de texto si se especifican encoding o errors o text en verdadero. Cuando se usa, el objeto Popen interno se crea automáticamente con stdin=PIPE y no se puede usar el argumento stdin a la vez.

Si check es verdadero y el proceso retorna un resultado distinto de cero, se lanzará una excepción CalledProcessError. Los atributos de dicha excepción contendrán los argumentos, el código retornado y tanto stdout como stderr si se capturaron.

Si se especifican encoding o errors o text es verdadero, se abrirán los objetos fichero para stdin, stdout y stderr en modo texto, con los encoding y errors especificados o los valores predeterminados de io.TextIOWrapper. El argumento universal_newlines equivale a text y se admite por compatibilidad hacia atrás. Los objetos fichero se abren en modo binario por defecto.

Si env no es None, debe ser un mapeo que defina las variables de entorno para el nuevo proceso; se utilizarán éstas en lugar del comportamiento predeterminado de heredar el entorno del proceso actual. Se le pasa directamente a Popen.

Ejemplos:

>>> subprocess.run(["ls", "-l"])  # doesn't capture output
CompletedProcess(args=['ls', '-l'], returncode=0)

>>> subprocess.run("exit 1", shell=True, check=True)
Traceback (most recent call last):
  ...
subprocess.CalledProcessError: Command 'exit 1' returned non-zero exit status 1

>>> subprocess.run(["ls", "-l", "/dev/null"], capture_output=True)
CompletedProcess(args=['ls', '-l', '/dev/null'], returncode=0,
stdout=b'crw-rw-rw- 1 root root 1, 3 Jan 23 16:23 /dev/null\n', stderr=b'')

Nuevo en la versión 3.5.

Distinto en la versión 3.6: Se añadieron los parámetros encoding y errors

Distinto en la versión 3.7: Se añadió el parámetro text como alias más comprensible de universal_newlines. Se añadió el parámetro capture_output.

Distinto en la versión 3.9.17: Changed Windows shell search order for shell=True. The current directory and %PATH% are replaced with %COMSPEC% and %SystemRoot%\System32\cmd.exe. As a result, dropping a malicious program named cmd.exe into a current directory no longer works.

class subprocess.CompletedProcess¶

El valor retornado por run(), que representa un proceso ya terminado.

args¶: Los argumentos utilizados para lanzar el proceso. Pueden ser una lista o una cadena.

returncode¶

Estado de salida del proceso hijo. Típicamente, un estado de salida 0 indica que la ejecución tuvo éxito.

Un valor negativo -N indica que el hijo fue forzado a terminar con la señal N (solamente POSIX).

stdout¶

La salida estándar capturada del proceso hijo. Una secuencia de bytes, o una cadena si se llamó a run() con encoding, errors, o text establecidos a True. None si no se capturó el error estándar.

Si se ejecutó el proceso con stderr=subprocess.STDOUT, stdout y stderr se combinarán en este atributo, y stderr será None.

stderr¶: El error estándar capturado del proceso hijo. Una secuencia de bytes, o una cadena si se llamó a run() con encoding, errors, o text establecidos a True. None si no se capturó el error estándar.

check_returncode()¶: Si returncode no es cero, lanza un CalledProcessError.

Nuevo en la versión 3.5.

subprocess.DEVNULL¶: Valor especial que se puede usar como argumento stdin, stdout o stderr de Popen y que indica que se usará el fichero especial os.devnull.

Nuevo en la versión 3.3.

subprocess.PIPE¶: Valor especial que se puede usar como argumento stdin, stdout o stderr de Popen y que indica que se abrirá un pipe al flujo indicado. Es útil para usarlo con Popen.communicate().

subprocess.STDOUT¶: Valor especial que se puede usar de argumento stderr a Popen y que indica que el error estándar debería ir al mismo gestor que la salida estándar.

exception subprocess.SubprocessError¶: Clase base para el resto de excepciones de este módulo.

Nuevo en la versión 3.3.

exception subprocess.TimeoutExpired¶

Subclase de SubprocessError, se lanza cuando expira un plazo de ejecución esperando a un proceso hijo.

cmd¶: Orden que se utilizó para lanzar el proceso hijo.

timeout¶: Plazo de ejecución en segundos.

output¶: Output of the child process if it was captured by run() or check_output(). Otherwise, None. This is always bytes when any output was captured regardless of the text=True setting. It may remain None instead of b'' when no output was observed.

stdout¶: Alias de output, por simetría con stderr.

stderr¶: Stderr output of the child process if it was captured by run(). Otherwise, None. This is always bytes when stderr output was captured regardless of the text=True setting. It may remain None instead of b'' when no stderr output was observed.

Nuevo en la versión 3.3.

Distinto en la versión 3.5: Se añadieron los atributos stdout y stderr

exception subprocess.CalledProcessError¶

Subclass of SubprocessError, raised when a process run by check_call(), check_output(), or run() (with check=True) returns a non-zero exit status.

returncode¶: Estado de salida del proceso hijo. Si el proceso terminó por causa de una señal, el estado será el número de la señal en negativo.

cmd¶: Orden que se utilizó para lanzar el proceso hijo.

output¶: Salida del proceso hijo si fue capturada por run() o check_output(). De otro modo, None.

stdout¶: Alias de output, por simetría con stderr.

stderr¶: Salida de stderr del proceso hijo si fue capturada por run(). De otro modo, None.

Distinto en la versión 3.5: Se añadieron los atributos stdout y stderr

Argumentos frecuentemente empleados¶

Para permitir una gran variedad de usos, el constructor de Popen (y las funciones asociadas) aceptan un gran número de argumentos opcionales. Para los usos más habituales, se pueden dejar de forma segura los valores por defecto. Los argumentos más frecuentemente necesarios son:

args se requiere en todas las llamadas; debe ser una cadena o una secuencia de argumentos al programa. En general, es mejor proporcionar una secuencia de argumentos porque permite que el módulo se ocupe de las secuencias de escape y los entrecomillados de los argumentos (por ejemplo, para permitir espacios en los nombres de fichero). Si se pasa una cadena simple, se ha de especificar shell como True (ver más adelante) o la cadena debe ser el nombre del programa a ejecutar sin especificar ningún argumento.

stdin, stdout and stderr specify the executed program’s standard input, standard output and standard error file handles, respectively. Valid values are PIPE, DEVNULL, an existing file descriptor (a positive integer), an existing file object with a valid file descriptor, and None. PIPE indicates that a new pipe to the child should be created. DEVNULL indicates that the special file os.devnull will be used. With the default settings of None, no redirection will occur; the child’s file handles will be inherited from the parent. Additionally, stderr can be STDOUT, which indicates that the stderr data from the child process should be captured into the same file handle as for stdout.

Si se especifican encoding o errors, o text (o su alias universal_newlines) es verdadero, se abrirán en modo texto los objetos fichero stdin, stdout y stderr usando los encoding y errors especificados en la llamada o los valores predeterminados de io.TextIOWrapper.

Para stdin, los saltos del línea '\n' de la entrada serán convertidos al separador de línea predeterminado os.linesep. Para stdout y stderr, todos los saltos de línea de la salida serán convertidos a '\n'. Hay más información en la documentación de la clase io.TextIOWrapper para el caso en que el argumento newline de su constructor es None.

Si no se usa el modo texto, stdin, stdout y stderr se abrirán como flujos binarios. No se realizará ninguna codificación ni conversión de salto de línea.

Nuevo en la versión 3.6: Se añadieron los parámetros encoding y errors.

Nuevo en la versión 3.7: Se añadió el parámetro text como alias de universal_newlines.

Nota

El atributo newlines de los objetos fichero Popen.stdin, Popen.stdout y Popen.stderr no es actualizado por el método Popen.communicate().

Si shell es True, la orden especificada se ejecutará pasando por la shell. Esto tiene utilidad si se usa Python principalmente por el flujo de control mejorado sobre la mayoría de las shell de sistema, pero se desea también un acceso práctico a otras características de la shell, como pipes, nombres de fichero con comodines, expansión de variables de entorno o expansión de ~ al directorio home del usuario. Sin embargo, no se debe olvidar que el propio Python tiene implementaciones de muchas características tipo shell (en particular, glob, fnmatch, os.walk(), os.path.expandvars(), os.path.expanduser(), y shutil).

Distinto en la versión 3.3: Cuando universal_newlines es True, la clase usa la codificación locale.getpreferredencoding(False) en lugar de locale.getpreferredencoding(). Ver la clase io.TextIOWrapper para obtener más información sobre este cambio.

Nota

Leer la sección Consideraciones sobre la seguridad antes de usar shell=True.

Estas opciones y el resto se describen con más detalle en la documentación del constructor de Popen.

El constructor de Popen¶

El proceso interno de creación y gestión de este módulo lo gestiona la clase Popen. Proporciona una gran flexibilidad para que los desarrolladores sean capaces de gestionar los casos menos comunes que quedan sin cubrir por las funciones auxiliares.

class subprocess.Popen(args, bufsize=-1, executable=None, stdin=None, stdout=None, stderr=None, preexec_fn=None, close_fds=True, shell=False, cwd=None, env=None, universal_newlines=None, startupinfo=None, creationflags=0, restore_signals=True, start_new_session=False, pass_fds=(), *, group=None, extra_groups=None, user=None, umask=-1, encoding=None, errors=None, text=None)¶

Ejecuta un programa hijo en un proceso nuevo. En POSIX, la clase se comporta como os.execvp() para lanzar el proceso hijo. En Windows, la clase usa la función CreateProcess() de Windows. Los argumentos de Popen son los siguientes.

args debe ser o una secuencia de argumentos de programa o una cadena simple o un objeto tipo ruta. Por omisión, el programa a ejecutar es el primer elemento de args si args es una secuencia. Si args es una cadena, la interpretación es dependiente de la plataforma, según se describe más abajo. Véase los argumentos shell y executable para más información sobre el comportamiento por defecto. Salvo que se indique, se recomienda pasar los args como una secuencia.

Un ejemplo del paso de argumentos a un programa externo mediante una secuencia:

Popen(["/usr/bin/git", "commit", "-m", "Fixes a bug."])

En POSIX, si args es una cadena se interpreta como el nombre o la ruta del programa que ejecutar. Sin embargo, esto solamente funciona si no hay que pasar argumentos al programa.

Nota

Puede que no resulte evidente cómo descomponer una orden de la shell en una secuencia de argumentos, especialmente en casos complejos. shlex.split() puede aclarar cómo determinar la descomposición en tokens de args:

>>> import shlex, subprocess
>>> command_line = input()
/bin/vikings -input eggs.txt -output "spam spam.txt" -cmd "echo '$MONEY'"
>>> args = shlex.split(command_line)
>>> print(args)
['/bin/vikings', '-input', 'eggs.txt', '-output', 'spam spam.txt', '-cmd', "echo '$MONEY'"]
>>> p = subprocess.Popen(args) # Success!

Hay que destacar en particular que las opciones (como -input) y los argumentos (como eggs.txt) que van separados por espacio en blanco en la shell van en elementos de lista separados, mientras los argumentos que necesitan entrecomillado o escapado de espacios cuando se usan en la shell (como los nombres de ficheros con espacios o la orden echo anteriormente mostrada) son elementos simples de la lista.

En Windows, si args es una secuencia, se convertirá a cadena del modo descrito en Cómo convertir una secuencia de argumentos a una cadena en Windows. Esto es así porque la función de bajo nivel CreateProcess() funciona sobre cadenas.

Distinto en la versión 3.6: El parámetro args toma un objeto tipo ruta si shell es False y una secuencia de objetos tipo fichero en POSIX.

Distinto en la versión 3.8: El parámetro args toma un objeto tipo ruta si shell es False y una secuencia de bytes y objetos tipo fichero en Windows.

El argumento shell (False``por defecto) especifica si usar la shell como programa a ejecutar. Si *shell* es ``True, se recomienda pasar args como cadena mejor que como secuencia.

En POSIX con shell=True, la shell predeterminada es /bin/sh. Si args es una cadena, ésta especifica la orden a ejecutar por la shell. Esto significa que la cadena tiene que tener el formato que tendría si se tecleara en la línea de órdenes. Esto incluye, por ejemplo, el entrecomillado y las secuencias de escape necesarias para los nombres de fichero que contengan espacios. Si args es una secuencia, el primer elemento especifica la cadena de la orden y cualquier otro elemento será tratado como argumentos adicionales a la propia shell. De este modo, Popen hace el equivalente de:

Popen(['/bin/sh', '-c', args[0], args[1], ...])

En Windows con shell=True, la variable de entorno COMSPEC especifica la shell predeterminada. Solamente hace falta especificar shell=True en Windows cuando la orden que se desea ejecutar es interna a la shell (como. dir o copy). No hace falta especificar shell=True para ejecutar un fichero por lotes o un ejecutable de consola.

Nota

Leer la sección Consideraciones sobre la seguridad antes de usar shell=True.

Se proporcionará bufsize como el argumento correspondiente a la función open() cuando se creen los objetos fichero de los flujos stdin/stdout/stderr:

0 significa sin búfer (read y write son una llamada al sistema y pueden retornar datos parciales)
1 significa usar búfer de líneas (solamente se puede usar si universal_newlines=True, es decir, en modo texto)
cualquier otro valor positivo indica que hay que usar un búfer de aproximadamente dicho tamaño
bufsize negativo (el valor por defecto) indica que se use el valor predeterminado del sistema, io.DEFAULT_BUFFER_SIZE.

Distinto en la versión 3.3.1: bufsize es ahora -1 por defecto para permitir que el buffering por defecto se comporte como o que la mayoría del código espera. En versiones anteriores a Python 3.2.4 o 3.3.1 tomaba un valor por defecto de 0, sin búfer, lo que permitía lecturas demasiado cortas. Esto no era intencionado y no se correspondía con el comportamiento de Python 2 como la mayoría de códigos esperan.

El argumento executable especifica un programa de reemplazo que ejecutar. Esto es muy poco frecuente. Cuando shell=False, executable reemplaza al programa especificado por args. Sin embargo, se pasan los args originales al programa. La mayoría de los programas tratan el programa especificado en los args como el nombre del programa, que puede ser diferente del programa realmente ejecutado. En POSIX, el nombre en args funciona como nombre visible en utilidades como ps. Si shell=True, en POSIX el argumento executable especifica una shell de reemplazo de la predeterminada /bin/sh.

Distinto en la versión 3.6: El parámetro executable acepta un objeto tipo ruta en POSIX.

Distinto en la versión 3.8: El parámetro executable acepta bytes y un objeto tipo ruta en POSIX.

Distinto en la versión 3.9.17: Changed Windows shell search order for shell=True. The current directory and %PATH% are replaced with %COMSPEC% and %SystemRoot%\System32\cmd.exe. As a result, dropping a malicious program named cmd.exe into a current directory no longer works.

stdin, stdout and stderr specify the executed program’s standard input, standard output and standard error file handles, respectively. Valid values are PIPE, DEVNULL, an existing file descriptor (a positive integer), an existing file object with a valid file descriptor, and None. PIPE indicates that a new pipe to the child should be created. DEVNULL indicates that the special file os.devnull will be used. With the default settings of None, no redirection will occur; the child’s file handles will be inherited from the parent. Additionally, stderr can be STDOUT, which indicates that the stderr data from the applications should be captured into the same file handle as for stdout.

Si se establece preexec_fn a un objeto invocable, se llamará a dicho objeto en el proceso hijo justo antes de que se ejecute el hijo. (solamente POSIX)

Advertencia

No es seguro utilizar el parámetro preexec_fn en presencia de hilos de ejecución en la aplicación. El proceso hijo podría bloquearse antes de llamar a exec. ¡Si es imprescindible, que sea tan simple como sea posible! Se ha de minimizar el número de librerías a las que se llama.

Nota

Si es necesario modificar el entorno para el proceso hijo, se debe utilizar el parámetro env en lugar de hacerlo en una preexec_fn. El parámetro start_new_session puede tomar el lugar de un uso anteriormente común de preexec_fn para llamar a os.setsid en el proceso hijo.

Distinto en la versión 3.8: Se ha abandonado el soporte de preexec_fn en subintérpretes. El uso de dicho parámetro en un subintérprete lanza RuntimeError. La nueva restricción puede afectar a aplicaciones desplegadas en mod_wsgi, uWSGI y otros entornos incrustados.

Si close_fds es verdadero, todos los descriptores de fichero salvo 0, 1 y 2 serán cerrados antes de ejecutar el proceso hijo. Por el contrario, cuando close_fds es falso, los descriptores de fichero obedecen su indicador de heredable según Herencia de los descriptores de archivos.

En Windows, si close_fds es verdadero el proceso hijo no heredará ningún gestor de fichero salvo que se le pasen explícitamente en el elemento handle_list de STARTUPINFO.lpAttributeList, o mediante redirección estándar.

Distinto en la versión 3.2: El valor predeterminado de close_fds se cambió de False a lo antes descrito.

Distinto en la versión 3.7: En Windows, el valor predeterminado de close_fds se cambió de False a True al redirigir los gestores estándar. Ahora es posible establecer close_fds a True cuando se redirigen los gestores estándar.

pass_fds es una secuencia de descriptor de ficheros opcional que han de mantenerse abiertos entre el proceso padre e hijo. Si se proporciona un valor a pass_fds se fuerza close_fds a True. (solamente POSIX)

Distinto en la versión 3.2: Se añadió el parámetro pass_fds.

Si cwd no es None, la función cambia el directorio de trabajo a cwd antes de ejecutar el proceso hijo. cwd puede ser una cadena, o un objeto bytes o tipo ruta. En particular, la función busca executable (o el primer elemento de args) relativo a cwd si la ruta del ejecutable es relativa.

Distinto en la versión 3.6: El parámetro cwd acepta un objeto tipo ruta en POSIX.

Distinto en la versión 3.7: El parámetro cwd acepta un objeto tipo ruta en Windows.

Distinto en la versión 3.8: El parámetro cwd acepta un objeto bytes en Windows.

Si restore_signals es verdadero (el valor por defecto) todas las señales que Python ha establecido a SIG_IGN se restauran a SIG_DFL en el proceso hijo antes del exec. En la actualidad, esto incluye las señales SIGPIPE, SIGXFZ y SIGXFSZ (solamente POSIX).

Distinto en la versión 3.2: Se añadió restore_signals.

Si start_new_session es verdadero la llamada al sistema setsid se hará en el proceso hijo antes de la ejecución del subproceso (solamente POSIX).

Distinto en la versión 3.2: Se añadió start_new_session.

Si group no es None, la llamada a sistema setregid() se hará en el proceso hijo antes de la ejecución del subproceso. Si el valor proveído es una cadena de caracteres, será buscado usando grp.getgrnam() y el valor en gr_gid será usado. Si el valor es un entero, será pasado literalmente. (solamente POSIX)

Disponibilidad: POSIX

Nuevo en la versión 3.9.

Si extra_groups no es None, la llamada a sistema setgroups() se hará en el proceso hijo antes de la ejecución del subproceso. Cadenas de caracteres proveídas en extra_groups serán buscadas usando grp.getgrnam() y los valores en gr_gid serán usados. Valor enteros serán pasados literalmente. (solamente POSIX)

Disponibilidad: POSIX

Nuevo en la versión 3.9.

Si user no es None, la llamada a sistema setreuid() se hará en el proceso hijo antes de la ejecución del subproceso. Si el valor proveído es una cadena de caracteres, será buscado usando pwd.getpwnam() y el valor en pw_uid será usado. Si el valor es un entero, será pasado literalmente. (solamente POSIX)

Disponibilidad: POSIX

Nuevo en la versión 3.9.

Si umask no es negativo, la llamada a sistema umask() se hará en el proceso hijo antes de la ejecución del subproceso.

Disponibilidad: POSIX

Nuevo en la versión 3.9.

Si env no es None, debe ser un mapeo que defina las variables de entorno del nuevo proceso; se utilizarán éstas en lugar del comportamiento por defecto de heredar el entorno del proceso en curso.

Nota

Si se especifica, env debe proporcionar las variables necesarias para que el programa se ejecute. En Windows, para ejecutar una side-by-side assembly el env especificado debe incluir un SystemRoot válido.

Si se especifica encoding o errors, o text verdadero, los objetos fichero stdin, stdout y stderr se abren en modo texto con la codificación y errors especificados, según se describió en Argumentos frecuentemente empleados. El argumento universal_newlines es equivalente a text y se admite por compatibilidad hacia atrás. Por omisión, los ficheros se abren en modo binario.

Nuevo en la versión 3.6: Se añadieron encoding y errors.

Nuevo en la versión 3.7: Se añadió text como alias más legible de universal_newlines.

Si se proporciona, startupinfo será un objeto STARTUPINFO, que se pasa a la función de más bajo nivel CreateProcess. creationflags, si está presente, puede ser uno o más de los siguientes indicadores:

CREATE_NEW_CONSOLE

CREATE_NEW_PROCESS_GROUP

ABOVE_NORMAL_PRIORITY_CLASS

BELOW_NORMAL_PRIORITY_CLASS

HIGH_PRIORITY_CLASS

IDLE_PRIORITY_CLASS

NORMAL_PRIORITY_CLASS

REALTIME_PRIORITY_CLASS

CREATE_NO_WINDOW

DETACHED_PROCESS

CREATE_DEFAULT_ERROR_MODE

CREATE_BREAKAWAY_FROM_JOB

Se puede usar los objetos Popen como gestores de contexto mediante sentencia with: a la salida, los descriptores de flujo se cierran y se espera a que acabe el proceso.

with Popen(["ifconfig"], stdout=PIPE) as proc:
    log.write(proc.stdout.read())

Lanza un evento de auditoría subprocess.Popen con argumentos executable, args, cwd, env.

Distinto en la versión 3.2: Se añadió la funcionalidad de gestor de contexto.

Distinto en la versión 3.6: El destructor de Popen ahora emite una advertencia ResourceWarning si el proceso hijo todavía se está ejecutando.

Distinto en la versión 3.8: Popen puede usar os.posix_spawn() en algunos casos para obtener mejor rendimiento. En el Subsistema de Windows para Linux (WSL) y en la emulación del modo usuario de QEMU, el constructor de Popen que use os.posix_spawn() ya no lanzará una excepción cuando se den errores tales como que un programa no esté, sino que el proceso hijo fracasará con un returncode distinto de cero.

Excepciones¶

Las excepciones lanzadas en el proceso hijo, antes de que el nuevo programa haya empezado a ejecutarse, se relanzarán en el padre.

The most common exception raised is OSError. This occurs, for example, when trying to execute a non-existent file. Applications should prepare for OSError exceptions. Note that, when shell=True, OSError will be raised by the child only if the selected shell itself was not found. To determine if the shell failed to find the requested application, it is necessary to check the return code or output from the subprocess.

Se lanzará un ValueError si se llama a Popen con argumentos no válidos.

check_call() y check_output() lanzarán un CalledProcessError si el proceso invocado retorna un código de retorno distinto de cero.

Todas las funciones y métodos que admiten un parámetro timeout, tales como call() y Popen.communicate() lanzarán TimeoutExpired si se vence el plazo de ejecución antes de que finalice el proceso hijo.

Todas las excepciones definidas en este módulo heredan de SubprocessError.

Nuevo en la versión 3.3: Se añadió la clase base SubprocessError.

Consideraciones sobre seguridad¶

Unlike some other popen functions, this library will not implicitly choose to call a system shell. This means that all characters, including shell metacharacters, can safely be passed to child processes. If the shell is invoked explicitly, via shell=True, it is the application’s responsibility to ensure that all whitespace and metacharacters are quoted appropriately to avoid shell injection vulnerabilities.

Cuando se usa shell=True, se puede usar la función shlex.quote() para escapar correctamente el espaciado y los metacaracteres de la shell en las cadenas que se vayan a utilizar para construir órdenes de la shell.

On Windows, batch files (*.bat or *.cmd) may be launched by the operating system in a system shell regardless of the arguments passed to this library. This could result in arguments being parsed according to shell rules, but without any escaping added by Python. If you are intentionally launching a batch file with arguments from untrusted sources, consider passing shell=True to allow Python to escape special characters. See gh-114539 for additional discussion.

Objetos Popen¶

Las instancias de la clase Popen cuentan con los siguientes métodos:

Popen.poll()¶: Comprueba si el proceso hijo ha finalizado. Establece y retorna el atributo returncode. De lo contrario, retorna None.

Popen.wait(timeout=None)¶

Espera a que termine el proceso hijo. Establece y retorna el atributo returncode.

Si el proceso no finaliza tras timeout segundos, lanza una excepción TimeoutExpired. Se puede capturar esta excepción para reintentar la espera.

Nota

Esto causará un bloqueo cuando se use stdout=PIPE o stderr=PIPE y el proceso hijo genere suficiente salida hacia un pipe como para bloquear esperando que el búfer del pipe del SO acepte más datos. Se debe usar Popen.communicate() cuando se usen pipes para evitar esto.

Nota

Esta función se implementa mediante una espera activa (llamada no bloqueante y breves llamadas a sleep). Se debe usar el módulo asyncio para hacer una espera asíncrona: ver asyncio.create_subprocess_exec.

Distinto en la versión 3.3: Se añadió timeout.

Popen.communicate(input=None, timeout=None)¶

Interactúa con el proceso: Envía datos a stdin. Lee datos de stdout y stderr hasta encontrar un fin-de-fichero. Espera a que termine el proceso y escribe el atributo returncode. El argumento opcional input debe contener los datos que hay que enviar al proceso hijo o None si no hay que enviar datos al proceso hijo. Si se abrieron los flujos en modo texto, input ha de ser una cadena de caracteres. En caso contrario, debe contener bytes.

communicate() retorna una tupla (stdout_data, stderr_data). Los datos serán cadenas si se abrieron los flujos en modo texto, en caso contrario serán bytes.

Adviértase que si se desea enviar datos al stdin del proceso, se ha de crear el objeto Popen con stdin=PIPE. Análogamente, para obtener algo diferente de None en la tupla del resultado, hay que suministrar stdout=PIPE o stderr=PIPE también.

Si el proceso no termina tras timeout segundos, se lanza una excepción TimeoutExpired. Si se captura dicha excepción y se reintenta la comunicación, no se perderán datos de salida.

No se matará el proceso si vence el plazo de ejecución, así que para hacer limpieza, una aplicación correcta debería matar el proceso y terminar la comunicación:

proc = subprocess.Popen(...)
try:
    outs, errs = proc.communicate(timeout=15)
except TimeoutExpired:
    proc.kill()
    outs, errs = proc.communicate()

Nota

Los datos leídos pasan por un búfer en memoria, así que no se ha de usar este método para un tamaño de datos grande o ilimitado.

Distinto en la versión 3.3: Se añadió timeout.

Popen.send_signal(signal)¶

Envía la señal signal al proceso hijo.

No hace nada si el proceso ya ha terminado.

Nota

En Windows, SIGTERM es un alias de terminate(). Se puede enviar CTRL_C_EVENT y CTRL_BREAK_EVENT a los procesos creados con un parámetro creationflags que incluya CREATE_NEW_PROCESS_GROUP.

Popen.terminate()¶: Detiene el proceso hijo. En sistemas operativos POSIX este método envía SIGTERM al proceso hijo. En Windows se llama a la función TerminateProcess() de la API de Win32 para detener el proceso hijo.

Popen.kill()¶: Mata el proceso hijo. En sistemas operativos POSIX la función envía SIGKILL al proceso hijo. En Windows kill() es un alias de terminate().

También están disponibles los siguientes atributos:

Popen.args¶: El argumento args según se pasó a Popen: o una secuencia de argumentos del programa o una cadena sencilla.

Nuevo en la versión 3.3.

Popen.stdin¶: Si el argumento stdin fue PIPE, este atributo es un objeto flujo escribible según lo retorna open(). Si se especificaron argumentos encoding o errors o el argumento universal_newlines fue True, el flujo es de texto, de lo contrario, es de bytes. Si el argumento stdin no fue PIPE, este atributo es None.

Popen.stdout¶: Si el argumento stdout fue PIPE, este atributo el un objeto de flujo legible según lo retorna open(). Leer del flujo proporciona salida del proceso hijo. Si se especificaron argumentos encoding o errors o el argumento universal_newlines fue True, el flujo es de texto, de lo contrario, es de bytes. Si el argumento stdout no fue PIPE, este atributo es None.

Popen.stderr¶: Si el argumento stderr fue PIPE, este atributo el un objeto de flujo legible según lo retorna open(). Leer del flujo proporciona salida del proceso hijo. Si se especificaron argumentos encoding o errors o el argumento universal_newlines fue True, el flujo es de texto, de lo contrario, es de bytes. Si el argumento stderr no fue PIPE, este atributo es None.

Advertencia

Se ha de usar communicate() en lugar de .stdin.write, .stdout.read o .stderr.read para evitar bloqueos por búfer de pipes del SO llenos que puedan bloquear el proceso hijo.

Popen.pid¶

El ID de proceso del hijo.

Adviértase que si se establece el argumento shell a True, éste es el ID de proceso del la shell generada.

Popen.returncode¶

El código de retorno del hijo, establecido por poll() y wait() (e indirectamente por communicate()). Un valor None indica que el proceso no ha terminado aún.

Un valor negativo -N indica que el hijo fue forzado a terminar con la señal N (solamente POSIX).

Elementos auxiliares de Popen en Windows¶

La clase STARTUPINFO y las siguientes constantes sólo están disponibles en Windows.

class subprocess.STARTUPINFO(*, dwFlags=0, hStdInput=None, hStdOutput=None, hStdError=None, wShowWindow=0, lpAttributeList=None)¶

Se utiliza un soporte parcial de la estructura STARTUPINFO de Windows para la creación de Popen. Se pueden establecer los siguientes atributos pasándolos como argumentos sólo por clave.

Distinto en la versión 3.7: Se añadió el soporte de argumentos sólo por clave.

dwFlags¶

Un campo bit que determina si se usan ciertos atributos de STARTUPINFO cuando el proceso crea una ventana.

si = subprocess.STARTUPINFO()
si.dwFlags = subprocess.STARTF_USESTDHANDLES | subprocess.STARTF_USESHOWWINDOW

hStdInput¶: Si dwFlags especifica STARTF_USESTDHANDLES, este atributo es el gestor de entrada estándar del proceso. Si no se especifica STARTF_USESTDHANDLES, el valor predeterminado de entrada estándar es el búfer de teclado.

hStdOutput¶: Si dwFlags especifica STARTF_USESTDHANDLES, este atributo es el gestor de salida estándar del proceso. En caso contrario, se hace caso omiso del atributo y el valor predeterminado de salida estándar es el búfer de ventana.

hStdError¶: Si dwFlags especifica STARTF_USESTDHANDLES, este atributo es el gestor de error estándar del proceso. En caso contrario, se hace caso omiso del atributo y el valor predeterminado de error estándar es el búfer de ventana.

wShowWindow¶

Si dwFlags especifica STARTF_USESHOWWINDOW, este atributo puede ser cualquiera de los valores que pueden especificarse en el parámetro nCmdShow para la función ShowWindow, salvo SW_SHOWDEFAULT. De otro modo, se hace caso omiso del atributo.

Se proporciona SW_HIDE para este atributo. Se usa cuando se llama a Popen con shell=True.

lpAttributeList¶

Un diccionario de atributos adicionales para la creación del proceso, según STARTUPINFOEX, véase UpdateProcThreadAttribute.

Atributos admitidos:

handle_list

Una secuencia de gestores que se heredará. close_fds debe ser verdadero si no viene vacío.

Los gestores deben hacerse temporalmente heredables por os.set_handle_inheritable() cuando se pasan al constructor de Popen o de lo contrario, se lanzará OSError con el error de Windows ERROR_INVALID_PARAMETER (87).

Advertencia

En un proceso multihilo, hay que evitar filtrar gestores no heredables cuando se combina esta característica con llamadas concurrentes a otras funciones de creación de procesos que heredan todos los gestores, como os.system(). Esto también rige para la redirección de gestores estándar, que crea temporalmente gestores heredables.

Nuevo en la versión 3.7.

Constantes de Windows¶

El módulo subprocess expone las siguientes constantes.

subprocess.STD_INPUT_HANDLE¶: El dispositivo de entrada estándar. Inicialmente, es el búfer de entrada de la consola, CONIN$.

subprocess.STD_OUTPUT_HANDLE¶: El dispositivo de salida estándar. Inicialmente, es el búfer de pantalla de la consola activa, CONOUT$.

subprocess.STD_ERROR_HANDLE¶: El dispositivo de error estándar. Inicialmente, es el búfer de pantalla de la consola activa, CONOUT$.

subprocess.SW_HIDE¶: Oculta la ventana. Se activará otra ventana.

subprocess.STARTF_USESTDHANDLES¶: Especifica que los atributos STARTUPINFO.hStdInput, STARTUPINFO.hStdOutput, y STARTUPINFO.hStdError contienen información adicional.

subprocess.STARTF_USESHOWWINDOW¶: Especifica que el atributo STARTUPINFO.wShowWindow contiene información adicional.

subprocess.CREATE_NEW_CONSOLE¶: El nuevo proceso obtiene una nueva consola, en lugar de heredar la consola del padre (que es el comportamiento predeterminado).

subprocess.CREATE_NEW_PROCESS_GROUP¶

Un parámetro Popen creationflags para especificar que se cree un nuevo grupo de procesos. Este indicador es necesario para usar os.kill() sobre el subproceso.

Este indicador no se tiene en cuenta si se especifica CREATE_NEW_CONSOLE.

subprocess.ABOVE_NORMAL_PRIORITY_CLASS¶: Parámetro Popen creationflags para especificar que el nuevo proceso tendrá una prioridad superior a la media.

Nuevo en la versión 3.7.

subprocess.BELOW_NORMAL_PRIORITY_CLASS¶: Parámetro Popen creationflags para especificar que el nuevo proceso tendrá una prioridad inferior a la media.

Nuevo en la versión 3.7.

subprocess.HIGH_PRIORITY_CLASS¶: Parámetro Popen creationflags para especificar que el nuevo proceso tendrá una prioridad elevada.

Nuevo en la versión 3.7.

subprocess.IDLE_PRIORITY_CLASS¶: Parámetro Popen creationflags para especificar que el nuevo proceso tendrá una la mínima prioridad.

Nuevo en la versión 3.7.

subprocess.NORMAL_PRIORITY_CLASS¶: Parámetro Popen creationflags para especificar que el nuevo proceso tendrá una prioridad normal (éste es el valor predeterminado).

Nuevo en la versión 3.7.

subprocess.REALTIME_PRIORITY_CLASS¶: Parámetro Popen creationflags para especificar que el nuevo proceso tendrá una prioridad de tiempo real. Raramente se debería usar REALTIME_PRIORITY_CLASS, porque esto interrumpe los hilos que gestionan la entrada del ratón y del teclado, así como la gestión del volcado de búfer del disco. Esta clase es apropiada para aplicaciones que se comunican directamente con el hardware o que llevan a cabo tareas breves que no admitan interrupciones.

Nuevo en la versión 3.7.

subprocess.CREATE_NO_WINDOW¶: Parámetro Popen creationflags para especificar que el nuevo proceso no creará una ventana.

Nuevo en la versión 3.7.

subprocess.DETACHED_PROCESS¶: Parámetro Popen creationflags para especificar que el nuevo proceso no heredará la consola del padre. Este valor es incompatible con CREATE_NEW_CONSOLE.

Nuevo en la versión 3.7.

subprocess.CREATE_DEFAULT_ERROR_MODE¶: Parámetro Popen creationflags para especificar que el nuevo proceso no hereda el modo de error del proceso padre. En su lugar, el proceso parte del modo de error predeterminado. Esta característica es particularmente útil para aplicaciones de shell multihilo que se ejecutan con los errores “duros” desactivados.

Nuevo en la versión 3.7.

subprocess.CREATE_BREAKAWAY_FROM_JOB¶: Parámetro Popen creationflags para especificar que el nuevo proceso no está asociado a la tarea.

Nuevo en la versión 3.7.

Antigua API de alto nivel¶

Antes de Python 3.5, estas tres funciones conformaban la API de alto nivel para subprocesos. Ahora se puede usar run() en muchos casos, pero hay mucho código escrito con estas funciones.

subprocess.call(args, *, stdin=None, stdout=None, stderr=None, shell=False, cwd=None, timeout=None, **other_popen_kwargs)¶

Ejecutar la orden descrita por args. Esperar que la orden se complete y retornar al atributo returncode.

El código que requiera capturar stdout o stderr debería usar run() en su lugar:

run(...).returncode

Para suprimir stdout o stderr se ha de proporcionar un valor de DEVNULL.

Se muestran algunos argumentos comunes. La signatura completa de la función es la misma que la del constructor de Popen; esta función pasa todos los argumentos proporcionados (salvo timeout) directamente a esa interfaz.

Nota

No usar stdout=PIPE ni stderr=PIPE con esta función. El proceso hijo se bloqueará si genera suficiente salida a un pipe como para saturar el búfer del pipe del sistema operativo mientras no se lee de los pipes.

Distinto en la versión 3.3: Se añadió timeout.

Distinto en la versión 3.9.17: Changed Windows shell search order for shell=True. The current directory and %PATH% are replaced with %COMSPEC% and %SystemRoot%\System32\cmd.exe. As a result, dropping a malicious program named cmd.exe into a current directory no longer works.

subprocess.check_call(args, *, stdin=None, stdout=None, stderr=None, shell=False, cwd=None, timeout=None, **other_popen_kwargs)¶

Run command with arguments. Wait for command to complete. If the return code was zero then return, otherwise raise CalledProcessError. The CalledProcessError object will have the return code in the returncode attribute. If check_call() was unable to start the process it will propagate the exception that was raised.

El código que requiera capturar stdout o stderr debería usar run() en su lugar:

run(..., check=True)

Para suprimir stdout o stderr se ha de proporcionar un valor de DEVNULL.

Se muestran algunos argumentos comunes. La signatura completa de la función es la misma que la del constructor de Popen; esta función pasa todos los argumentos proporcionados (salvo timeout) directamente a esa interfaz.

Nota

No usar stdout=PIPE ni stderr=PIPE con esta función. El proceso hijo se bloqueará si genera suficiente salida a un pipe como para saturar el búfer del pipe del sistema operativo mientras no se lee de los pipes.

Distinto en la versión 3.3: Se añadió timeout.

Distinto en la versión 3.9.17: Changed Windows shell search order for shell=True. The current directory and %PATH% are replaced with %COMSPEC% and %SystemRoot%\System32\cmd.exe. As a result, dropping a malicious program named cmd.exe into a current directory no longer works.

subprocess.check_output(args, *, stdin=None, stderr=None, shell=False, cwd=None, encoding=None, errors=None, universal_newlines=None, timeout=None, text=None, **other_popen_kwargs)¶

Ejecuta orden con argumentos y retorna su salida.

Si el código de retorno fue diferente de cero lanza un CalledProcessError. El objeto CalledProcessError tendrá el código de retorno en el atributo returncode y los datos de salida en el atributo output.

Esto equivale a:

run(..., check=True, stdout=PIPE).stdout

Los argumentos mostrados arriba son meramente algunos de los comunes. La signatura completa de la función es casi la misma que la de run() - la mayoría de los argumentos se pasa directamente a esa interfaz. Existe una diferencia con la interfaz de run() respecto al comportamiento: pasar input=None genera el mismo comportamiento que input=b'' (o input='', dependiendo de otros argumentos) en vez de usar el flujo entrada estándar del padre.

Por omisión, esta función retornará los datos como bytes codificados. La codificación real de los datos podría depender de la orden invocada, por lo que la decodificación a texto se deberá hacer al nivel de la aplicación.

Este comportamiento se puede modificar estableciendo text, encoding, errors, o universal_newlines a True, como se describe en Argumentos frecuentemente empleados y run().

Para capturar también el error estándar del resultado se debe usar stderr=subprocess.STDOUT:

>>> subprocess.check_output(
...     "ls non_existent_file; exit 0",
...     stderr=subprocess.STDOUT,
...     shell=True)
'ls: non_existent_file: No such file or directory\n'

Nuevo en la versión 3.1.

Distinto en la versión 3.3: Se añadió timeout.

Distinto en la versión 3.4: Se añadió soporte para el argumento por clave input.

Distinto en la versión 3.6: Se añadieron encoding y errors. Ver run() para más detalles.

Nuevo en la versión 3.7: Se añadió text como alias más legible de universal_newlines.

Distinto en la versión 3.9.17: Changed Windows shell search order for shell=True. The current directory and %PATH% are replaced with %COMSPEC% and %SystemRoot%\System32\cmd.exe. As a result, dropping a malicious program named cmd.exe into a current directory no longer works.

Cómo reemplazar anteriores funciones con el módulo `subprocess`¶

En esta sección, «a se convierte en b» significa que b se puede usar en lugar de.

Nota

Todas las funciones «a» de esta sección fracasan silenciosamente (o casi) si no se halla el programa ejecutado; las funciones de reemplazo «b» lanzan OSError en lugar de esto.

Además, las funciones de reemplazo que usan check_output() fracasarán con un error CalledProcessError si la operación solicitada produce un código de retorno diferente de cero. La salida queda disponible en el atributo output de la excepción lanzada.

En los siguientes ejemplos, se asume que las funciones relevantes ya han sido importadas del módulo subprocess.

Cómo reemplazar la sustitución de órdenes de /bin/sh¶

output=$(mycmd myarg)

se convierte en:

output = check_output(["mycmd", "myarg"])

Cómo remplazar los flujos de la shell¶

output=$(dmesg | grep hda)

se convierte en:

p1 = Popen(["dmesg"], stdout=PIPE)
p2 = Popen(["grep", "hda"], stdin=p1.stdout, stdout=PIPE)
p1.stdout.close()  # Allow p1 to receive a SIGPIPE if p2 exits.
output = p2.communicate()[0]

La llamada a p1.stdout.close() tras lanzar p2 es importante para que p1 reciba un SIGPIPE si p2 retorna antes que p1.

Alternativamente, para entrada de confianza, se puede usar el propio soporte de pipeline de la shell directamente:

output=$(dmesg | grep hda)

se convierte en:

output=check_output("dmesg | grep hda", shell=True)

Cómo reemplazar `os.system()`¶

sts = os.system("mycmd" + " myarg")
# becomes
retcode = call("mycmd" + " myarg", shell=True)

Notas:

No suele hacer falta llamar al programa a través de la shell.
The call() return value is encoded differently to that of os.system().
The os.system() function ignores SIGINT and SIGQUIT signals while the command is running, but the caller must do this separately when using the subprocess module.

Un ejemplo más creíble:

try:
    retcode = call("mycmd" + " myarg", shell=True)
    if retcode < 0:
        print("Child was terminated by signal", -retcode, file=sys.stderr)
    else:
        print("Child returned", retcode, file=sys.stderr)
except OSError as e:
    print("Execution failed:", e, file=sys.stderr)

Cómo reemplazar la familia `os.spawn`¶

Ejemplo de P_NOWAIT:

pid = os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg")
==>
pid = Popen(["/bin/mycmd", "myarg"]).pid

Ejemplo de P_WAIT:

retcode = os.spawnlp(os.P_WAIT, "/bin/mycmd", "mycmd", "myarg")
==>
retcode = call(["/bin/mycmd", "myarg"])

Ejemplo de vector:

os.spawnvp(os.P_NOWAIT, path, args)
==>
Popen([path] + args[1:])

Ejemplo de entorno:

os.spawnlpe(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg", env)
==>
Popen(["/bin/mycmd", "myarg"], env={"PATH": "/usr/bin"})

Cómo reemplazar `os.popen()`, `os.popen2()`, `os.popen3()`¶

(child_stdin, child_stdout) = os.popen2(cmd, mode, bufsize)
==>
p = Popen(cmd, shell=True, bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, close_fds=True)
(child_stdin, child_stdout) = (p.stdin, p.stdout)

(child_stdin,
 child_stdout,
 child_stderr) = os.popen3(cmd, mode, bufsize)
==>
p = Popen(cmd, shell=True, bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, stderr=PIPE, close_fds=True)
(child_stdin,
 child_stdout,
 child_stderr) = (p.stdin, p.stdout, p.stderr)

(child_stdin, child_stdout_and_stderr) = os.popen4(cmd, mode, bufsize)
==>
p = Popen(cmd, shell=True, bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, stderr=STDOUT, close_fds=True)
(child_stdin, child_stdout_and_stderr) = (p.stdin, p.stdout)

La gestión del código de retorno se traduce así:

pipe = os.popen(cmd, 'w')
...
rc = pipe.close()
if rc is not None and rc >> 8:
    print("There were some errors")
==>
process = Popen(cmd, stdin=PIPE)
...
process.stdin.close()
if process.wait() != 0:
    print("There were some errors")

Cómo reemplazar las funciones del módulo `popen2`¶

Nota

Si el argumento cmd de las funciones popen2 es una cadena, la orden se ejecuta a través de /bin/sh. Si es una lista, la orden se ejecuta directamente.

(child_stdout, child_stdin) = popen2.popen2("somestring", bufsize, mode)
==>
p = Popen("somestring", shell=True, bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, close_fds=True)
(child_stdout, child_stdin) = (p.stdout, p.stdin)

(child_stdout, child_stdin) = popen2.popen2(["mycmd", "myarg"], bufsize, mode)
==>
p = Popen(["mycmd", "myarg"], bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, close_fds=True)
(child_stdout, child_stdin) = (p.stdout, p.stdin)

popen2.Popen3 y popen2.Popen4 funcionan a grandes rasgos como subprocess.Popen, salvo:

Popen lanza una excepción si falla la ejecución.
El argumento capturestderr se sustituye por el argumento stderr.
Se ha de especificar stdin=PIPE y stdout=PIPE.
popen2 cierra todos los descriptores de fichero por omisión, pero se ha de especificar close_fds=True con Popen para garantizar este comportamiento en todas las plataformas o en versiones anteriores de Python.

Funciones de llamada a la shell de retrocompatibilidad¶

Este módulo también proporciona las siguientes funciones de compatibilidad del módulo commands de las versiones 2.X. Estas operaciones invocan implícitamente a la shell del sistema y no se les aplican ninguna de las garantías descritas anteriormente respecto a seguridad o consistencia en la gestión de excepciones.

subprocess.getstatusoutput(cmd)¶

Retorna (exitcode, output) de ejecutar cmd en una shell.

Ejecuta la cadena cmd en una shell con Popen.check_output() y retorna una tupla (exitcode, output). Se utiliza la codificación de localización activa; consultar las notas sobre Argumentos frecuentemente empleados para más información.

Se elimina un salto de línea final de la salida. El código de salida de la orden se puede interpretar como el código de retorno del subproceso. Por ejemplo:

>>> subprocess.getstatusoutput('ls /bin/ls')
(0, '/bin/ls')
>>> subprocess.getstatusoutput('cat /bin/junk')
(1, 'cat: /bin/junk: No such file or directory')
>>> subprocess.getstatusoutput('/bin/junk')
(127, 'sh: /bin/junk: not found')
>>> subprocess.getstatusoutput('/bin/kill $$')
(-15, '')

Disponibilidad: POSIX y Windows.

Distinto en la versión 3.3.4: Se añadió soporte de Windows.

La función ahora retorna (exitcode, output) en lugar de (status, output) como en Python 3.3.3 y anteriores. exitcode tiene el mismo valor que returncode.

subprocess.getoutput(cmd)¶

Retorna la salida (stdout y stderr) de ejecutar cmd en una shell.

Como getstatusoutput(), salvo que se ignora el código de salida y el valor retornado es una cadena que contiene la salida del comando. Por ejemplo:

>>> subprocess.getoutput('ls /bin/ls')
'/bin/ls'

Disponibilidad: POSIX y Windows.

Distinto en la versión 3.3.4: Se añadió soporte de Windows

Notas¶

Cómo convertir una secuencia de argumentos a una cadena en Windows¶

En Windows, para convertir una secuencia args en una cadena que puede ser analizada con las siguientes reglas (correspondientes a las reglas que usa la biblioteca de ejecución de MS C):

Los argumentos se separan por espacio en blanco, que debe ser un espacio o un tabulador.
Una cadena entre comillas dobles se interpreta como un argumento simple, sin importar los espacios en blanco que contenga. Se puede incrustar una cadena entre comillas en un argumento.
Una comilla doble precedida de una barra invertida se interpreta literalmente como una comilla doble.
Las barras invertidas se interpretan literalmente, salvo que precedan a una comilla doble.
Si las barras invertidas preceden inmediatamente a una doble comilla, cada par de barras invertidas se interpreta como una barra invertida literal. Si el número de barras invertidas es impar, la última barra invertida escapa la siguiente comilla doble según se describe en la regla 3.

Ver también

shlex: Módulo que proporciona una función para analizar y escapar líneas de órdenes.

`subprocess` — Gestión de subprocesos¶

Uso del módulo `subprocess`¶

Argumentos frecuentemente empleados¶

El constructor de Popen¶

Excepciones¶

Consideraciones sobre seguridad¶

Objetos Popen¶

Elementos auxiliares de Popen en Windows¶

Constantes de Windows¶

Antigua API de alto nivel¶

Cómo reemplazar anteriores funciones con el módulo `subprocess`¶

Cómo reemplazar la sustitución de órdenes de /bin/sh¶

Cómo remplazar los flujos de la shell¶

Cómo reemplazar `os.system()`¶

Cómo reemplazar la familia `os.spawn`¶

Cómo reemplazar `os.popen()`, `os.popen2()`, `os.popen3()`¶

Cómo reemplazar las funciones del módulo `popen2`¶

Funciones de llamada a la shell de retrocompatibilidad¶

Notas¶

Cómo convertir una secuencia de argumentos a una cadena en Windows¶

Tabla de contenido

Tema anterior

Próximo tema

Esta página

subprocess — Gestión de subprocesos¶

Uso del módulo subprocess¶

Argumentos frecuentemente empleados¶

El constructor de Popen¶

Excepciones¶

Consideraciones sobre seguridad¶

Objetos Popen¶

Elementos auxiliares de Popen en Windows¶

Constantes de Windows¶

Antigua API de alto nivel¶

Cómo reemplazar anteriores funciones con el módulo subprocess¶

Cómo reemplazar la sustitución de órdenes de /bin/sh¶

Cómo remplazar los flujos de la shell¶

Cómo reemplazar os.system()¶

Cómo reemplazar la familia os.spawn¶

Cómo reemplazar os.popen(), os.popen2(), os.popen3()¶

Cómo reemplazar las funciones del módulo popen2¶

Funciones de llamada a la shell de retrocompatibilidad¶

Notas¶

Cómo convertir una secuencia de argumentos a una cadena en Windows¶

`subprocess` — Gestión de subprocesos¶

Uso del módulo `subprocess`¶

Cómo reemplazar anteriores funciones con el módulo `subprocess`¶

Cómo reemplazar `os.system()`¶

Cómo reemplazar la familia `os.spawn`¶

Cómo reemplazar `os.popen()`, `os.popen2()`, `os.popen3()`¶

Cómo reemplazar las funciones del módulo `popen2`¶