subprocess — Управление подпроцессами

Исходный код: Lib/subprocess.py

Модуль subprocess позволяет запускать новые процессы, подключаться к их каналам ввода/вывода/ошибок и получать коды возврата. Этот модуль предназначен для замены нескольких устаревших модулей и функций:

os.system
os.spawn*

Информация о том, как можно использовать модуль subprocess для замены этих модулей и функций, приведена в следующих разделах.

См. также

PEP 324 — PEP с предложением добавить модуль subprocess

Доступность: недоступен на Android, iOS и WASI.

Этот модуль не поддерживается на мобильных платформах и платформах WebAssembly.

Использование модуля subprocess

Рекомендуемый способ запуска подпроцессов во всех подходящих случаях — использовать функцию run(). Для более сложных случаев можно напрямую использовать базовый интерфейс Popen.

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)

Выполняет команду, заданную аргументом args. Ожидает завершения команды, а затем возвращает экземпляр CompletedProcess.

Приведённые выше аргументы — лишь наиболее распространённые, описанные ниже в разделе Часто используемые аргументы (отсюда и использование обозначения аргументов только по ключевому слову в сокращённой сигнатуре). Полная сигнатура функции во многом совпадает с сигнатурой конструктора Popen — большая часть аргументов этой функции передаётся этому интерфейсу. (timeout, input, check и capture_output не передаются.)

Если capture_output имеет значение true, stdout и stderr будут перехвачены. При использовании этого параметра внутренний объект Popen автоматически создаётся с параметрами stdout и stderr, установленными в PIPE. Аргументы stdout и stderr нельзя указывать одновременно с capture_output. Чтобы перехватить оба потока и объединить их в один, установите для stdout значение PIPE, а для stderr — STDOUT, вместо использования capture_output.

Параметр timeout можно указать в секундах; он передаётся методу Popen.communicate(). Если время ожидания истечёт, дочерний процесс будет завершён, и программа дождётся его завершения. После завершения дочернего процесса будет повторно вызвано исключение TimeoutExpired. На многих платформах создание процесса невозможно прервать с помощью API, поэтому исключение о превышении времени ожидания может возникнуть только после того, как пройдёт время, необходимое для создания процесса.

Аргумент input передаётся методу Popen.communicate(), а оттуда — стандартному потоку ввода подпроцесса. Если он используется, его значением должна быть последовательность байтов либо строка, если указаны encoding или errors либо параметр text имеет значение true. При использовании этого аргумента внутренний объект Popen автоматически создаётся с параметром stdin, установленным в PIPE; аргумент stdin также использовать нельзя.

Если check имеет значение true и процесс завершается с ненулевым кодом выхода, будет вызвано исключение CalledProcessError. Атрибуты этого исключения содержат аргументы, код выхода, а также stdout и stderr, если они были перехвачены.

Если указаны encoding или errors либо параметр text имеет значение true, файловые объекты stdin, stdout и stderr открываются в текстовом режиме с использованием указанных значений encoding и errors или параметров по умолчанию io.TextIOWrapper. Аргумент universal_newlines эквивалентен text и предусмотрен для обратной совместимости. По умолчанию файловые объекты открываются в двоичном режиме.

Если значение env не равно None, оно должно быть отображением, задающим переменные среды для нового процесса; эти переменные используются вместо стандартного поведения, при котором наследуется среда текущего процесса. Значение передаётся непосредственно в Popen. Это отображение может содержать строки в качестве ключей и значений на любой платформе или байты в качестве ключей и значений на POSIX-платформах, подобно os.environ или os.environb.

Примеры:

>>> 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'')

Добавлено в версии 3.5.

Изменено в версии 3.6: Добавлены параметры encoding и errors

Изменено в версии 3.7: Добавлен параметр text — более понятный псевдоним universal_newlines. Добавлен параметр capture_output.

Изменено в версии 3.12: Изменён порядок поиска оболочки в Windows для shell=True. Текущий каталог и %PATH% заменяются на %COMSPEC% и %SystemRoot%\System32\cmd.exe. В результате размещение вредоносной программы с именем cmd.exe в текущем каталоге больше не работает.

class subprocess.CompletedProcess

Возвращаемое значение run(), представляющее завершившийся процесс.

args: Аргументы, использованные для запуска процесса. Это может быть список или строка.

returncode

Код завершения дочернего процесса. Обычно код завершения 0 означает, что процесс выполнен успешно.

Отрицательное значение -N означает, что дочерний процесс завершён сигналом N (только POSIX).

stdout

Перехваченный stdout дочернего процесса. Последовательность байтов или строка, если run() вызвана с параметром encoding, errors или text=True. None, если stdout не перехватывался.

Если вы запустили процесс с параметром stderr=subprocess.STDOUT, stdout и stderr будут объединены в этом атрибуте, а stderr будет иметь значение None.

stderr: Перехваченный stderr дочернего процесса. Последовательность байтов или строка, если run() вызвана с параметром encoding, errors или text=True. None, если stderr не перехватывался.

check_returncode(): Если returncode не равен нулю, вызывает исключение CalledProcessError.

Добавлено в версии 3.5.

subprocess.DEVNULL: Специальное значение, которое можно использовать в качестве аргумента stdin, stdout или stderr для Popen; оно указывает, что будет использоваться специальный файл os.devnull.

Добавлено в версии 3.3.

subprocess.PIPE: Специальное значение, которое можно использовать в качестве аргумента stdin, stdout или stderr для Popen; оно указывает, что для стандартного потока должен быть открыт канал. Особенно полезно в сочетании с Popen.communicate().

subprocess.STDOUT: Специальное значение, которое можно использовать в качестве аргумента stderr для Popen; оно указывает, что стандартный поток ошибок должен использовать тот же дескриптор, что и стандартный поток вывода.

exception subprocess.SubprocessError: Базовый класс для всех остальных исключений этого модуля.

Добавлено в версии 3.3.

exception subprocess.TimeoutExpired

Подкласс SubprocessError, вызываемый при истечении времени ожидания дочернего процесса.

cmd: Команда, использованная для запуска дочернего процесса.

timeout: Время ожидания в секундах.

output: Вывод дочернего процесса, если он был перехвачен функцией run() или check_output(). В противном случае — None. Если какой-либо вывод был перехвачен, это значение всегда имеет тип bytes, независимо от настройки text=True. Если вывод не был получен, значение может остаться None, а не b''.

stdout: Псевдоним output, обеспечивающий симметрию с stderr.

stderr: Вывод stderr дочернего процесса, если он был перехвачен функцией run(). В противном случае — None. Если вывод stderr был перехвачен, это значение всегда имеет тип bytes, независимо от настройки text=True. Если вывод stderr не был получен, значение может остаться None, а не b''.

Добавлено в версии 3.3.

Изменено в версии 3.5: Добавлены атрибуты stdout и stderr

exception subprocess.CalledProcessError

Подкласс SubprocessError, вызываемый, когда процесс, запущенный функцией check_call(), check_output() или run() (с параметром check=True), завершается с ненулевым кодом выхода.

returncode: Код завершения дочернего процесса. Если процесс завершился из-за сигнала, здесь будет указано отрицательное значение номера сигнала.

cmd: Команда, использованная для запуска дочернего процесса.

output: Вывод дочернего процесса, если он был перехвачен функцией run() или check_output(). В противном случае — None.

stdout: Псевдоним output, обеспечивающий симметрию с stderr.

stderr: Вывод stderr дочернего процесса, если он был перехвачен функцией run(). В противном случае — None.

Изменено в версии 3.5: Добавлены атрибуты stdout и stderr

Часто используемые аргументы

Чтобы поддерживать самые разные сценарии использования, конструктор Popen (а также функции-обёртки) принимает большое количество необязательных аргументов. В большинстве типичных случаев многие из этих аргументов можно безопасно оставить со значениями по умолчанию. Чаще всего нужны следующие аргументы:

args обязателен во всех вызовах и должен быть строкой или последовательностью аргументов программы. Обычно предпочтительнее передавать последовательность аргументов, поскольку это позволяет модулю самостоятельно выполнять необходимое экранирование и заключение аргументов в кавычки (например, чтобы разрешить пробелы в именах файлов). Если передаётся одна строка, параметр shell должен иметь значение True (см. ниже), либо строка должна просто указывать имя запускаемой программы без аргументов.

Аргументы stdin, stdout и stderr задают дескрипторы файлов стандартного ввода, стандартного вывода и стандартного потока ошибок запускаемой программы соответственно. Допустимые значения: None, PIPE, DEVNULL, существующий файловый дескриптор (положительное целое число) и существующий файловый объект с допустимым файловым дескриптором. При стандартных настройках None перенаправление не выполняется. PIPE означает, что для дочернего процесса следует создать новый канал. DEVNULL означает, что будет использоваться специальный файл os.devnull. Кроме того, для stderr можно указать STDOUT, что означает, что данные stderr дочернего процесса будут записываться в тот же файловый дескриптор, что и stdout.

Если указаны encoding или errors либо параметр text (также известный как universal_newlines) имеет значение true, файловые объекты stdin, stdout и stderr будут открыты в текстовом режиме с использованием значений encoding и errors, заданных в вызове, либо значений по умолчанию для io.TextIOWrapper.

Для stdin символы окончания строки '\n' во входных данных будут преобразованы в разделитель строк по умолчанию os.linesep. Для stdout и stderr все окончания строк в выходных данных будут преобразованы в '\n'. Дополнительную информацию см. в документации класса io.TextIOWrapper, если аргумент newline его конструктора имеет значение None.

Если текстовый режим не используется, stdin, stdout и stderr будут открыты как двоичные потоки. Кодирование и преобразование окончаний строк не выполняются.

Изменено в версии 3.6: Добавлены параметры encoding и errors.

Изменено в версии 3.7: Добавлен параметр text как псевдоним universal_newlines.

Примечание

Атрибут newlines файловых объектов Popen.stdin, Popen.stdout и Popen.stderr не обновляется методом Popen.communicate().

Если shell имеет значение True, указанная команда выполняется через оболочку. Это может быть полезно, если вы используете Python главным образом ради более гибкого управления потоком выполнения по сравнению с большинством системных оболочек, но при этом хотите иметь удобный доступ к другим возможностям оболочки, таким как каналы, подстановочные знаки в именах файлов, раскрытие переменных среды и раскрытие ~ в домашний каталог пользователя. Однако Python сам предоставляет реализации многих возможностей, обычно связанных с оболочками (в частности, glob, fnmatch, os.walk(), os.path.expandvars(), os.path.expanduser() и shutil).

Изменено в версии 3.3: Если universal_newlines имеет значение True, класс использует кодировку locale.getpreferredencoding(False) вместо locale.getpreferredencoding(). Дополнительные сведения об этом изменении см. в документации класса io.TextIOWrapper.

Примечание

Перед использованием shell=True ознакомьтесь с разделом Рекомендации по безопасности.

Эти и все остальные параметры подробнее описаны в документации конструктора Popen.

Конструктор Popen

Создание и управление процессами в этом модуле выполняется классом Popen. Он предоставляет широкие возможности, позволяя разработчикам обрабатывать менее распространённые случаи, не охваченные вспомогательными функциями.

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, pipesize=-1, process_group=None)

Выполняет дочернюю программу в новом процессе. В POSIX этот класс использует поведение, подобное os.execvpe(), для выполнения дочерней программы. В Windows класс использует функцию Windows CreateProcess(). Аргументы Popen следующие.

args должен быть последовательностью аргументов программы либо одной строкой или объектом, подобным пути. По умолчанию, если args — последовательность, выполняемой программой становится её первый элемент. Если args — строка, её интерпретация зависит от платформы и описана ниже. О других отличиях от поведения по умолчанию см. аргументы shell и executable. Если не указано иное, рекомендуется передавать args как последовательность.

Предупреждение

Для максимальной надёжности используйте полный путь к исполняемому файлу. Чтобы найти имя без полного пути в PATH, используйте shutil.which(). На всех платформах рекомендуется передавать sys.executable, чтобы снова запустить текущий интерпретатор Python, а для запуска установленного модуля используйте формат командной строки -m.

Правила разрешения пути к executable (или к первому элементу args) зависят от платформы. Для POSIX см. os.execvpe(); обратите внимание, что при разрешении или поиске пути к исполняемому файлу cwd переопределяет текущий рабочий каталог, а env может переопределить переменную окружения PATH. Для Windows см. документацию по параметрам lpApplicationName и lpCommandLine функции WinAPI CreateProcess; обратите внимание, что при разрешении или поиске пути к исполняемому файлу с помощью shell=False cwd не переопределяет текущий рабочий каталог, а env не может переопределить переменную окружения PATH. Полный путь позволяет избежать всех этих различий.

Пример передачи внешней программе нескольких аргументов в виде последовательности:

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

В POSIX, если args — строка, она интерпретируется как имя или путь программы для выполнения. Однако это возможно только в том случае, если программе не передаются аргументы.

Примечание

Разбить команду оболочки на последовательность аргументов может быть непросто, особенно в сложных случаях. shlex.split() поможет определить правильное разбиение на токены для 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!

Обратите особое внимание: параметры (например, -input) и аргументы (например, eggs.txt), разделённые пробелами в оболочке, должны быть отдельными элементами списка, а аргументы, для которых при использовании в оболочке требуются кавычки или экранирование обратной косой чертой (например, имена файлов с пробелами или показанная выше команда echo), должны быть одним элементом списка.

В Windows, если args — последовательность, она будет преобразована в строку способом, описанным в разделе Преобразование последовательности аргументов в строку в Windows. Это связано с тем, что базовая CreateProcess() работает со строками.

Изменено в версии 3.6: Параметр args принимает объект, подобный пути, если shell имеет значение False, и последовательность, содержащую объекты, подобные пути, в POSIX.

Изменено в версии 3.8: Параметр args принимает объект, подобный пути, если shell имеет значение False, и последовательность, содержащую байты и объекты, подобные пути, в Windows.

Аргумент shell (по умолчанию имеет значение False) определяет, следует ли использовать оболочку в качестве выполняемой программы. Если shell имеет значение True, рекомендуется передавать args строкой, а не последовательностью.

В POSIX с shell=True оболочкой по умолчанию является /bin/sh. Если args — строка, она задаёт команду, выполняемую через оболочку. Это значит, что строка должна быть отформатирована точно так же, как при вводе в приглашении оболочки. Например, имена файлов с пробелами необходимо заключать в кавычки или экранировать обратной косой чертой. Если args — последовательность, первый элемент задаёт строку команды, а все последующие элементы трактуются как дополнительные аргументы самой оболочки. Иными словами, Popen выполняет эквивалент следующего:

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

В Windows с shell=True переменная окружения COMSPEC указывает оболочку по умолчанию. Указывать shell=True в Windows нужно только тогда, когда требуемая команда встроена в оболочку (например, dir или copy). Для запуска пакетного файла или консольного исполняемого файла указывать shell=True не требуется.

Примечание

Перед использованием shell=True ознакомьтесь с разделом Рекомендации по безопасности.

bufsize будет передан в качестве соответствующего аргумента функции open() при создании файловых объектов каналов stdin/stdout/stderr:

0 означает отсутствие буферизации (чтение и запись выполняются одним системным вызовом, который может вернуть меньше данных, чем запрошено)
1 означает буферизацию построчно (допустимо только при text=True или universal_newlines=True)
любое другое положительное значение означает использование буфера приблизительно такого размера
отрицательное значение bufsize (по умолчанию) означает использование системного размера буфера io.DEFAULT_BUFFER_SIZE.

Изменено в версии 3.3.1: Теперь значение bufsize по умолчанию равно -1, чтобы включить буферизацию и обеспечить ожидаемое поведение большинства программ. В версиях до Python 3.2.4 и 3.3.1 по ошибке использовалось значение 0, которое отключало буферизацию и допускало короткие чтения. Это было непреднамеренно и не соответствовало поведению Python 2, которого ожидало большинство программ.

Аргумент executable задаёт заменяющую программу для выполнения. Он нужен крайне редко. Если указано shell=False, executable заменяет программу, заданную для выполнения аргументом args. Однако исходный args по-прежнему передаётся программе. Большинство программ воспринимают программу, указанную в args, как имя команды, которое может отличаться от фактически выполняемой программы. В POSIX имя из args становится отображаемым именем исполняемого файла в таких утилитах, как ps. Если указано shell=True, в POSIX аргумент executable задаёт оболочку, заменяющую оболочку по умолчанию /bin/sh.

Изменено в версии 3.6: Параметр executable принимает объект, подобный пути в POSIX.

Изменено в версии 3.8: Параметр executable принимает объект bytes и объект, подобный пути в Windows.

stdin, stdout и stderr задают файловые дескрипторы стандартного ввода, стандартного вывода и стандартного потока ошибок выполняемой программы соответственно. Допустимые значения: None, PIPE, DEVNULL, существующий файловый дескриптор (положительное целое число) и существующий файловый объект с действительным файловым дескриптором. При настройках None по умолчанию перенаправление не выполняется. PIPE указывает, что для дочернего процесса следует создать новый канал. DEVNULL указывает, что будет использоваться специальный файл os.devnull. Кроме того, для stderr можно указать STDOUT, чтобы данные stderr приложений сохранялись в том же файловом дескрипторе, что и stdout.

Если для preexec_fn задан вызываемый объект, он будет вызван в дочернем процессе непосредственно перед выполнением дочерней программы. (Только POSIX)

Предупреждение

Параметр preexec_fn НЕБЕЗОПАСНО использовать в приложении с потоками. До вызова exec в дочернем процессе может возникнуть взаимная блокировка.

Примечание

Если нужно изменить среду дочернего процесса, используйте параметр env, а не preexec_fn. Параметры start_new_session и process_group заменяют код, использующий preexec_fn для вызова os.setsid() или os.setpgid() в дочернем процессе.

Изменено в версии 3.8: Параметр preexec_fn больше не поддерживается во вложенных интерпретаторах. Использование этого параметра во вложенном интерпретаторе вызывает RuntimeError. Новое ограничение может затронуть приложения, развёрнутые в mod_wsgi, uWSGI и других встраиваемых средах.

Если close_fds имеет значение true, перед выполнением дочернего процесса будут закрыты все файловые дескрипторы, кроме 0, 1 и 2. Если же close_fds имеет значение false, файловые дескрипторы подчиняются своему флагу наследования, как описано в разделе Наследование файловых дескрипторов.

В Windows, если close_fds имеет значение true, дочерний процесс не унаследует дескрипторы, если они явно не переданы в элементе handle_list объекта STARTUPINFO.lpAttributeList или через перенаправление стандартных дескрипторов.

Изменено в версии 3.2: Значение close_fds по умолчанию было изменено с False на описанное выше.

Изменено в версии 3.7: В Windows значение close_fds по умолчанию при перенаправлении стандартных дескрипторов было изменено с False на True. Теперь при перенаправлении стандартных дескрипторов можно задать для close_fds значение True.

pass_fds — необязательная последовательность файловых дескрипторов, которые следует оставить открытыми между родительским и дочерним процессами. Передача любого значения pass_fds принудительно устанавливает для close_fds значение True. (Только POSIX)

Изменено в версии 3.2: Добавлен параметр pass_fds.

Если cwd не равен None, функция меняет рабочий каталог на cwd перед выполнением дочернего процесса. cwd может быть строкой, байтами или объектом, подобным пути. В POSIX функция ищет executable (или первый элемент args) относительно cwd, если путь к исполняемому файлу относительный.

Изменено в версии 3.6: Параметр cwd принимает объект, подобный пути в POSIX.

Изменено в версии 3.7: Параметр cwd принимает объект, подобный пути в Windows.

Изменено в версии 3.8: Параметр cwd принимает объект bytes в Windows.

Если restore_signals имеет значение true (по умолчанию), все сигналы, для которых Python установил SIG_IGN, восстанавливаются до SIG_DFL в дочернем процессе перед вызовом exec. В настоящее время это сигналы SIGPIPE, SIGXFZ и SIGXFSZ. (Только POSIX)

Изменено в версии 3.2: Добавлен параметр restore_signals.

Если start_new_session имеет значение true, системный вызов setsid() будет выполнен в дочернем процессе до запуска подпроцесса.

Доступность: POSIX

Изменено в версии 3.2: Добавлен параметр start_new_session.

Если process_group — неотрицательное целое число, системный вызов setpgid(0, value) будет выполнен в дочернем процессе до запуска подпроцесса.

Доступность: POSIX

Изменено в версии 3.11: Добавлен параметр process_group.

Если group не равен None, системный вызов setregid() будет выполнен в дочернем процессе до запуска подпроцесса. Если задано строковое значение, оно будет найдено с помощью grp.getgrnam(), а затем будет использовано значение из gr_gid. Целочисленное значение передаётся без изменений. (Только POSIX)

Доступность: POSIX

Добавлено в версии 3.9.

Если extra_groups не равен None, системный вызов setgroups() будет выполнен в дочернем процессе до запуска подпроцесса. Строки, переданные в extra_groups, будут найдены с помощью grp.getgrnam(), после чего будут использованы значения из gr_gid. Целочисленные значения передаются без изменений. (Только POSIX)

Доступность: POSIX

Добавлено в версии 3.9.

Если user не равен None, системный вызов setreuid() будет выполнен в дочернем процессе до запуска подпроцесса. Если задано строковое значение, оно будет найдено с помощью pwd.getpwnam(), а затем будет использовано значение из pw_uid. Целочисленное значение передаётся без изменений. (Только POSIX)

Доступность: POSIX

Добавлено в версии 3.9.

Если значение umask неотрицательное, системный вызов umask() будет выполнен в дочернем процессе до запуска подпроцесса.

Доступность: POSIX

Добавлено в версии 3.9.

Если env не равен None, это должно быть отображение, задающее переменные окружения для нового процесса; они используются вместо поведения по умолчанию, при котором наследуется окружение текущего процесса. На любой платформе это отображение может связывать строки со строками, а на платформах POSIX — байты с байтами, подобно os.environ или os.environb.

Примечание

Если параметр env указан, он должен содержать все переменные, необходимые для запуска программы. В Windows для запуска сборки Side-by-Side указанное значение env должно содержать действительный SystemRoot.

Если указаны encoding или errors либо text имеет значение true, файловые объекты stdin, stdout и stderr открываются в текстовом режиме с указанными значениями encoding и errors, как описано выше в разделе Часто используемые аргументы. Аргумент universal_newlines эквивалентен text и предоставлен для обратной совместимости. По умолчанию файловые объекты открываются в двоичном режиме.

Добавлено в версии 3.6: Добавлены параметры encoding и errors.

Добавлено в версии 3.7: Добавлен text — более понятное альтернативное имя для universal_newlines.

Если задан, startupinfo будет объектом STARTUPINFO, который передаётся базовой функции CreateProcess.

Если задан, creationflags может содержать один или несколько следующих флагов:

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

Параметр pipesize позволяет изменить размер канала, если для stdin, stdout или stderr используется PIPE. Размер канала изменяется только на платформах, поддерживающих эту возможность (на момент написания — только Linux). На других платформах этот параметр игнорируется.

Изменено в версии 3.10: Добавлен параметр pipesize.

Объекты Popen поддерживают использование в качестве менеджеров контекста с помощью оператора with: при выходе из контекста стандартные файловые дескрипторы закрываются, а выполнение процесса ожидается.

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

Popen и другие функции этого модуля, использующие его, вызывают событие аудита subprocess.Popen с аргументами executable, args, cwd и env. Значение args может быть одной строкой или списком строк в зависимости от платформы.

Изменено в версии 3.2: Добавлена поддержка менеджеров контекста.

Изменено в версии 3.6: Деструктор Popen теперь выдаёт предупреждение ResourceWarning, если дочерний процесс всё ещё выполняется.

Изменено в версии 3.8: В некоторых случаях Popen может использовать os.posix_spawn() для повышения производительности. В Windows Subsystem for Linux и эмуляции пользовательского режима QEMU конструктор Popen, использующий os.posix_spawn(), при таких ошибках, как отсутствие программы, больше не вызывает исключение; вместо этого дочерний процесс завершается с ненулевым значением returncode.

Исключения

Исключения, возникающие в дочернем процессе до начала выполнения новой программы, будут повторно вызваны в родительском процессе.

Наиболее часто возникает исключение OSError. Например, оно возникает при попытке выполнить несуществующий файл. Приложения должны предусматривать обработку исключений OSError. Обратите внимание: при shell=True исключение OSError будет вызвано дочерним процессом только в том случае, если выбранная оболочка не найдена. Чтобы определить, не удалось ли оболочке найти запрошенное приложение, необходимо проверить код возврата или вывод подпроцесса.

Если Popen вызван с недопустимыми аргументами, будет вызвано исключение ValueError.

check_call() и check_output() вызовут CalledProcessError, если вызванный процесс завершится с ненулевым кодом возврата.

Все функции и методы, принимающие параметр timeout, такие как run() и Popen.communicate(), вызовут TimeoutExpired, если время ожидания истечёт до завершения процесса.

Все исключения, определённые в этом модуле, являются подклассами SubprocessError.

Добавлено в версии 3.3: Добавлен базовый класс SubprocessError.

Объекты Popen

Экземпляры класса Popen имеют следующие методы:

Popen.poll(): Проверяет, завершился ли дочерний процесс. Устанавливает и возвращает атрибут returncode. В противном случае возвращает None.

Popen.wait(timeout=None)

Ожидает завершения дочернего процесса. Устанавливает и возвращает атрибут returncode.

Если процесс не завершится за timeout секунд, возбуждается исключение TimeoutExpired. Это исключение можно безопасно перехватить и повторить ожидание.

Примечание

Это приведёт к взаимной блокировке при использовании stdout=PIPE или stderr=PIPE, если дочерний процесс выведет в канал достаточно данных, чтобы заблокироваться в ожидании, пока буфер канала ОС освободит место для новых данных. Используйте Popen.communicate() при работе с каналами, чтобы избежать этого.

Примечание

Если параметр timeout не равен None, то (в POSIX) функция реализована с использованием активного цикла (неблокирующий вызов и короткие паузы). Для асинхронного ожидания используйте модуль asyncio: см. asyncio.create_subprocess_exec.

Изменено в версии 3.3: Добавлен параметр timeout.

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

Взаимодействует с процессом: отправляет данные в stdin. Читает данные из stdout и stderr до достижения конца файла. Ожидает завершения процесса и устанавливает атрибут returncode. Необязательный аргумент input должен содержать данные для отправки дочернему процессу или None, если дочернему процессу не нужно отправлять данные. Если потоки открыты в текстовом режиме, input должен быть строкой. В противном случае он должен быть байтовой последовательностью.

communicate() возвращает кортеж (stdout_data, stderr_data). Если потоки открыты в текстовом режиме, данные будут строками; в противном случае — байтовыми последовательностями.

Обратите внимание: если вы хотите отправить данные в stdin процесса, необходимо создать объект Popen с stdin=PIPE. Аналогично, чтобы получить в кортеже результата что-либо, кроме None, необходимо также указать stdout=PIPE и/или stderr=PIPE.

Если процесс не завершится за timeout секунд, будет возбуждено исключение TimeoutExpired. Перехват этого исключения и повторная попытка взаимодействия не приведут к потере каких-либо выходных данных.

При истечении времени ожидания дочерний процесс не завершается, поэтому для надлежащей очистки хорошо написанное приложение должно завершить дочерний процесс и закончить взаимодействие:

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

Примечание

Прочитанные данные буферизуются в памяти, поэтому не используйте этот метод, если объём данных велик или не ограничен.

Изменено в версии 3.3: Добавлен параметр timeout.

Popen.send_signal(signal)

Отправляет дочернему процессу сигнал signal.

Ничего не делает, если процесс завершён.

Примечание

В Windows SIGTERM является псевдонимом для terminate(). События CTRL_C_EVENT и CTRL_BREAK_EVENT можно отправлять процессам, запущенным с параметром creationflags, включающим CREATE_NEW_PROCESS_GROUP.

Popen.terminate(): Останавливает дочерний процесс. В POSIX ОС этот метод отправляет дочернему процессу сигнал SIGTERM. В Windows для остановки дочернего процесса вызывается функция Win32 API TerminateProcess().

Popen.kill(): Убивает дочерний процесс. В POSIX ОС функция отправляет дочернему процессу SIGKILL. В Windows kill() является псевдонимом для terminate().

Класс также устанавливает следующие атрибуты для доступа к ним. Переназначение им новых значений не поддерживается:

Popen.args: Аргумент args в том виде, в каком он был передан в Popen: последовательность аргументов программы или одна строка.

Добавлено в версии 3.3.

Popen.stdin: Если аргумент stdin равен PIPE, этот атрибут является доступным для записи объектом потока, возвращаемым функцией open(). Если указаны аргументы encoding или errors либо аргумент text или universal_newlines равен True, поток является текстовым; в противном случае это байтовый поток. Если аргумент stdin не равен PIPE, этот атрибут равен None.

Popen.stdout: Если аргумент stdout равен PIPE, этот атрибут является доступным для чтения объектом потока, возвращаемым функцией open(). Чтение из потока предоставляет выходные данные дочернего процесса. Если указаны аргументы encoding или errors либо аргумент text или universal_newlines равен True, поток является текстовым; в противном случае это байтовый поток. Если аргумент stdout не равен PIPE, этот атрибут равен None.

Popen.stderr: Если аргумент stderr равен PIPE, этот атрибут является доступным для чтения объектом потока, возвращаемым функцией open(). Чтение из потока предоставляет сообщения об ошибках дочернего процесса. Если указаны аргументы encoding или errors либо аргумент text или universal_newlines равен True, поток является текстовым; в противном случае это байтовый поток. Если аргумент stderr не равен PIPE, этот атрибут равен None.

Предупреждение

Используйте communicate(), а не .stdin.write, .stdout.read или .stderr.read, чтобы избежать взаимной блокировки из-за заполнения буферов других каналов ОС, которое блокирует дочерний процесс.

Popen.pid

Идентификатор процесса дочернего процесса.

Обратите внимание: если для аргумента shell задано значение True, это идентификатор запущенной оболочки.

Popen.returncode

Код возврата дочернего процесса. Изначально равный None, returncode устанавливается вызовом методов poll(), wait() или communicate(), если они обнаруживают, что процесс завершился.

Значение None указывает, что на момент последнего вызова метода процесс ещё не завершился.

Отрицательное значение -N означает, что дочерний процесс был завершён сигналом N (только POSIX).

Вспомогательные средства Popen для Windows

Класс STARTUPINFO и следующие константы доступны только в Windows.

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

Для создания Popen используется частичная поддержка структуры Windows STARTUPINFO. Следующие атрибуты можно задать, передав их как аргументы только по имени.

Изменено в версии 3.7: Добавлена поддержка аргументов только по имени.

dwFlags

Битовое поле, определяющее, используются ли некоторые атрибуты STARTUPINFO при создании окном процесса.

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

hStdInput: Если dwFlags указывает STARTF_USESTDHANDLES, этот атрибут является дескриптором стандартного ввода процесса. Если STARTF_USESTDHANDLES не указан, по умолчанию стандартным вводом является буфер клавиатуры.

hStdOutput: Если dwFlags указывает STARTF_USESTDHANDLES, этот атрибут является дескриптором стандартного вывода процесса. В противном случае атрибут игнорируется, а стандартным выводом по умолчанию является буфер окна консоли.

hStdError: Если dwFlags указывает STARTF_USESTDHANDLES, этот атрибут является дескриптором стандартного потока ошибок процесса. В противном случае атрибут игнорируется, а стандартным потоком ошибок по умолчанию является буфер окна консоли.

wShowWindow

Если dwFlags указывает STARTF_USESHOWWINDOW, этот атрибут может принимать любое значение, допустимое для параметра nCmdShow функции ShowWindow, кроме SW_SHOWDEFAULT. В противном случае атрибут игнорируется.

Для этого атрибута предусмотрено значение SW_HIDE. Оно используется, когда Popen вызывается с shell=True.

lpAttributeList

Словарь дополнительных атрибутов для создания процесса, заданных в STARTUPINFOEX; см. UpdateProcThreadAttribute.

Поддерживаемые атрибуты:

handle_list

Последовательность дескрипторов, которые будут унаследованы. Если последовательность непустая, параметр close_fds должен иметь значение true.

При передаче конструктору Popen дескрипторы необходимо временно сделать наследуемыми с помощью os.set_handle_inheritable(), иначе будет возбуждено исключение OSError с кодом ошибки Windows ERROR_INVALID_PARAMETER (87).

Предупреждение

В многопоточном процессе будьте осторожны, чтобы избежать утечки дескрипторов, помеченных как наследуемые, при совместном использовании этой возможности с одновременными вызовами других функций создания процессов, наследующих все дескрипторы, например os.system(). Это также относится к перенаправлению стандартных дескрипторов, при котором временно создаются наследуемые дескрипторы.

Добавлено в версии 3.7.

Константы Windows

Модуль subprocess предоставляет следующие константы.

subprocess.STD_INPUT_HANDLE: Устройство стандартного ввода. Изначально это буфер ввода консоли, CONIN$.

subprocess.STD_OUTPUT_HANDLE: Устройство стандартного вывода. Изначально это активный буфер экрана консоли, CONOUT$.

subprocess.STD_ERROR_HANDLE: Устройство стандартного потока ошибок. Изначально это активный буфер экрана консоли, CONOUT$.

subprocess.SW_HIDE: Скрывает окно. Активируется другое окно.

subprocess.STARTF_USESTDHANDLES: Указывает, что атрибуты STARTUPINFO.hStdInput, STARTUPINFO.hStdOutput и STARTUPINFO.hStdError содержат дополнительную информацию.

subprocess.STARTF_USESHOWWINDOW: Указывает, что атрибут STARTUPINFO.wShowWindow содержит дополнительную информацию.

subprocess.STARTF_FORCEONFEEDBACK: Параметр STARTUPINFO.dwFlags, указывающий, что при запуске процесса будет отображаться указатель мыши «Работа в фоновом режиме». Это поведение по умолчанию для процессов с графическим интерфейсом.

Добавлено в версии 3.13.

subprocess.STARTF_FORCEOFFFEEDBACK: Параметр STARTUPINFO.dwFlags, указывающий, что при запуске процесса указатель мыши не будет изменён.

Добавлено в версии 3.13.

subprocess.CREATE_NEW_CONSOLE: Новый процесс получает новую консоль вместо наследования консоли родительского процесса (поведение по умолчанию).

subprocess.CREATE_NEW_PROCESS_GROUP

Параметр creationflags для Popen, указывающий, что будет создана новая группа процессов. Этот флаг необходим для использования os.kill() для подпроцесса.

Этот флаг игнорируется, если указан CREATE_NEW_CONSOLE.

subprocess.ABOVE_NORMAL_PRIORITY_CLASS: Параметр creationflags для Popen, указывающий, что новый процесс будет иметь приоритет выше среднего.

Добавлено в версии 3.7.

subprocess.BELOW_NORMAL_PRIORITY_CLASS: Параметр creationflags для Popen, указывающий, что новый процесс будет иметь приоритет ниже среднего.

Добавлено в версии 3.7.

subprocess.HIGH_PRIORITY_CLASS: Параметр creationflags для Popen, указывающий, что новый процесс будет иметь высокий приоритет.

Добавлено в версии 3.7.

subprocess.IDLE_PRIORITY_CLASS: Параметр creationflags для Popen, указывающий, что новый процесс будет иметь фоновый (самый низкий) приоритет.

Добавлено в версии 3.7.

subprocess.NORMAL_PRIORITY_CLASS: Параметр creationflags для Popen, указывающий, что новый процесс будет иметь обычный приоритет (по умолчанию).

Добавлено в версии 3.7.

subprocess.REALTIME_PRIORITY_CLASS: Параметр creationflags для Popen, указывающий, что новый процесс будет иметь приоритет реального времени. Почти никогда не следует использовать REALTIME_PRIORITY_CLASS, поскольку он прерывает системные потоки, отвечающие за обработку ввода с мыши и клавиатуры, а также фоновую запись данных на диск. Этот класс может подходить для приложений, напрямую взаимодействующих с оборудованием, или выполняющих кратковременные задачи, которые должны как можно реже прерываться.

Добавлено в версии 3.7.

subprocess.CREATE_NO_WINDOW: Параметр creationflags для Popen, указывающий, что новый процесс не будет создавать окно.

Добавлено в версии 3.7.

subprocess.DETACHED_PROCESS: Параметр creationflags для Popen, указывающий, что новый процесс не будет наследовать консоль родительского процесса. Это значение нельзя использовать вместе с CREATE_NEW_CONSOLE.

Добавлено в версии 3.7.

subprocess.CREATE_DEFAULT_ERROR_MODE: Параметр creationflags для Popen, указывающий, что новый процесс не будет наследовать режим обработки ошибок вызывающего процесса. Вместо этого новый процесс получит режим обработки ошибок по умолчанию. Эта возможность особенно полезна для многопоточных приложений-оболочек, работающих с отключённой обработкой критических ошибок.

Добавлено в версии 3.7.

subprocess.CREATE_BREAKAWAY_FROM_JOB: Параметр creationflags для Popen, указывающий, что новый процесс не связан с заданием.

Добавлено в версии 3.7.

Устаревший высокоуровневый API

До Python 3.5 эти три функции составляли высокоуровневый API для работы с подпроцессами. Во многих случаях теперь можно использовать run(), но множество существующих программ вызывает эти функции.

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

Запускает команду, описанную в args. Ожидает завершения команды, а затем возвращает атрибут returncode.

Для перехвата stdout или stderr следует использовать run():

run(...).returncode

Чтобы отключить stdout или stderr, укажите значение DEVNULL.

Показанные выше аргументы — лишь некоторые из часто используемых. Полная сигнатура функции совпадает с сигнатурой конструктора Popen: эта функция передаёт все предоставленные аргументы, кроме timeout, непосредственно этому интерфейсу.

Примечание

Не используйте stdout=PIPE или stderr=PIPE с этой функцией. Дочерний процесс заблокируется, если сгенерирует достаточно данных для заполнения буфера канала ОС, поскольку данные из каналов не считываются.

Изменено в версии 3.3: Добавлен параметр timeout.

Изменено в версии 3.12: Изменён порядок поиска команд оболочкой Windows для shell=True. Текущий каталог и %PATH% заменяются на %COMSPEC% и %SystemRoot%\System32\cmd.exe. В результате размещение вредоносной программы с именем cmd.exe в текущем каталоге больше не работает.

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

Запускает команду с аргументами. Ожидает завершения команды. Если код возврата равен нулю, возвращает управление, в противном случае возбуждает исключение CalledProcessError. Объект CalledProcessError будет содержать код возврата в атрибуте returncode. Если check_call() не удалось запустить процесс, будет передано возникшее исключение.

Для перехвата stdout или stderr следует использовать run():

run(..., check=True)

Чтобы отключить stdout или stderr, укажите значение DEVNULL.

Примечание

Изменено в версии 3.3: Добавлен параметр timeout.

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)

Запускает команду с аргументами и возвращает её вывод.

Если код возврата ненулевой, возбуждается исключение CalledProcessError. Объект CalledProcessError будет содержать код возврата в атрибуте returncode, а вывод — в атрибуте output.

Это эквивалентно:

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

Показанные выше аргументы — лишь некоторые из часто используемых. Полная сигнатура функции в основном совпадает с сигнатурой run() — большинство аргументов передаются непосредственно этому интерфейсу. Есть одно отличие API от поведения run(): передача input=None будет вести себя так же, как input=b'' (или input='', в зависимости от других аргументов), а не использовать дескриптор файла стандартного ввода родительского процесса.

По умолчанию эта функция возвращает данные в виде закодированных байтов. Фактическая кодировка выходных данных может зависеть от вызываемой команды, поэтому декодирование в текст часто необходимо выполнять на уровне приложения.

Это поведение можно изменить, задав для text, encoding, errors или universal_newlines значение True, как описано в разделах Часто используемые аргументы и run().

Чтобы также включить стандартный поток ошибок в результат, используйте 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'

Добавлено в версии 3.1.

Изменено в версии 3.3: Добавлен параметр timeout.

Изменено в версии 3.4: Добавлена поддержка именованного аргумента input.

Изменено в версии 3.6: Добавлены encoding и errors. Подробности см. в описании run().

Добавлено в версии 3.7: Добавлен text как более понятный псевдоним для universal_newlines.

Замена устаревших функций модулем subprocess

В этом разделе выражение «a заменяется на b» означает, что b можно использовать вместо a.

Примечание

Все функции «a» в этом разделе (в той или иной степени) молча завершаются, если исполняемая программа не найдена; функции-замены «b» вместо этого возбуждают исключение OSError.

Кроме того, замены, использующие check_output(), возбуждают исключение CalledProcessError, если запрошенная операция возвращает ненулевой код. Вывод при этом по-прежнему доступен в атрибуте output возбуждённого исключения.

В приведённых ниже примерах предполагается, что соответствующие функции уже импортированы из модуля subprocess.

Замена подстановки команды оболочки /bin/sh

output=$(mycmd myarg)

заменяется на:

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

Замена конвейера оболочки

output=$(dmesg | grep hda)

заменяется на:

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]

Вызов p1.stdout.close() после запуска p2 важен, чтобы p1 получил SIGPIPE, если p2 завершится раньше p1.

В качестве альтернативы для доверенного ввода можно напрямую использовать встроенную поддержку конвейеров оболочкой:

output=$(dmesg | grep hda)

заменяется на:

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

Замена `os.system()`

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

Примечания:

Обычно нет необходимости запускать программу через оболочку.
Возвращаемое значение call() кодируется иначе, чем значение os.system().
Функция os.system() игнорирует сигналы SIGINT и SIGQUIT во время выполнения команды, однако при использовании модуля subprocess вызывающий код должен делать это самостоятельно.

Более реалистичный пример выглядел бы так:

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)

Замена семейства функций `os.spawn`

Пример с P_NOWAIT:

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

Пример с P_WAIT:

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

Пример с вектором:

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

Пример с окружением:

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

Замена `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)

Обработка кода возврата соответствует следующему:

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")

Замена функций модуля `popen2`

Примечание

Если аргумент cmd функций popen2 является строкой, команда выполняется через /bin/sh. Если это список, команда выполняется напрямую.

(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 и popen2.Popen4 в основном работают так же, как subprocess.Popen, за исключением того, что:

Popen возбуждает исключение, если выполнить запуск не удаётся.
Аргумент capturestderr заменён аргументом stderr.
Необходимо указать stdin=PIPE и stdout=PIPE.
popen2 по умолчанию закрывает все файловые дескрипторы, но для гарантии такого поведения на всех платформах или в предыдущих версиях Python необходимо указать close_fds=True при вызове Popen.

Устаревшие функции вызова оболочки

Этот модуль также предоставляет следующие устаревшие функции из модуля commands версии 2.x. Эти операции неявно вызывают системную оболочку, поэтому описанные выше гарантии безопасности и единообразной обработки исключений для них не действуют.

subprocess.getstatusoutput(cmd, *, encoding=None, errors=None)

Возвращает (exitcode, output) выполнения cmd в оболочке.

Выполняет строку cmd в оболочке с Popen.check_output() и возвращает 2-кортеж (exitcode, output). Параметры encoding и errors используются для декодирования вывода; дополнительные сведения см. в примечаниях к разделу Часто используемые аргументы.

Завершающий символ новой строки удаляется из вывода. Код завершения команды можно интерпретировать как код возврата подпроцесса. Пример:

>>> 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, '')

Доступность: Unix, Windows.

Изменено в версии 3.3.4: Добавлена поддержка Windows.

Теперь функция возвращает (exitcode, output) вместо (status, output), как в Python 3.3.3 и более ранних версиях. Значение exitcode совпадает со значением returncode.

Изменено в версии 3.11: Добавлены параметры encoding и errors.

subprocess.getoutput(cmd, *, encoding=None, errors=None)

Возвращает вывод (stdout и stderr) выполнения cmd в оболочке.

Работает как getstatusoutput(), за исключением того, что код завершения игнорируется, а возвращаемое значение — строка с выводом команды. Пример:

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

Доступность: Unix, Windows.

Изменено в версии 3.3.4: Добавлена поддержка Windows.

Изменено в версии 3.11: Добавлены параметры encoding и errors.

Примечания

Поведение при тайм-ауте

При использовании параметра timeout в таких функциях, как run(), Popen.wait() или Popen.communicate(), следует учитывать следующие особенности:

Задержка при создании процесса: На многих платформах создание процесса нельзя прервать с помощью API. Это означает, что даже при заданном тайм-ауте исключение о превышении времени ожидания может возникнуть только после завершения создания процесса.
Чрезвычайно малые значения тайм-аута: Если задать очень малое значение тайм-аута (например, несколько миллисекунд), исключение TimeoutExpired может возникнуть почти сразу, поскольку создание процесса и планирование задач операционной системой неизбежно требуют времени.

Преобразование последовательности аргументов в строку в Windows

В Windows последовательность args преобразуется в строку, которую можно разобрать по следующим правилам (они соответствуют правилам, используемым средой выполнения MS C):

Аргументы разделяются пробельными символами: пробелом или табуляцией.
Строка, заключённая в двойные кавычки, считается одним аргументом независимо от содержащихся в ней пробельных символов. Строка в кавычках может быть частью аргумента.
Двойная кавычка, перед которой стоит обратная косая черта, интерпретируется как буквальная двойная кавычка.
Обратные косые черты интерпретируются буквально, если только непосредственно за ними не следует двойная кавычка.
Если непосредственно перед двойной кавычкой стоят обратные косые черты, каждая пара обратных косых черт интерпретируется как одна буквальная обратная косая черта. Если количество обратных косых черт нечётное, последняя обратная косая черта экранирует следующую двойную кавычку, как описано в правиле 3.

См. также

shlex: Модуль, предоставляющий функции для разбора и экранирования командных строк.

Отключение использования `vfork()` или `posix_spawn()`

В Linux модуль subprocess по умолчанию использует системный вызов vfork(), если это безопасно, вместо fork(). Это значительно повышает производительность.

Если вы столкнулись с предположительно крайне необычной ситуацией, в которой необходимо запретить Python использовать vfork(), можно присвоить атрибуту subprocess._USE_VFORK значение False.

subprocess._USE_VFORK = False  # See CPython issue gh-NNNNNN.

Это не влияет на использование posix_spawn(), которая может использовать vfork() внутри своей реализации libc. Если необходимо запретить её использование, предусмотрен похожий атрибут subprocess._USE_POSIX_SPAWN.

subprocess._USE_POSIX_SPAWN = False  # See CPython issue gh-NNNNNN.

Эти атрибуты безопасно устанавливать в False в любой версии Python. В неподдерживаемых старых версиях это ни на что не повлияет. Не следует предполагать, что атрибуты доступны для чтения. Несмотря на названия, значение True не означает, что соответствующая функция будет использоваться, а лишь указывает на такую возможность.

Всякий раз, когда вам приходится использовать эти непубличные настройки, сообщайте об ошибке и указывайте способ воспроизведения проблемы. Добавьте ссылку на это сообщение об ошибке в комментарий к своему коду.

Добавлено в версии 3.8: _USE_POSIX_SPAWN

Добавлено в версии 3.11: _USE_VFORK

© 2001–2025 Python Software Foundation
Licensed under the PSF License.
https://docs.python.org/3.13/library/subprocess.html

subprocess — Управление подпроцессами

Использование модуля subprocess

Часто используемые аргументы

Конструктор Popen

Исключения

Рекомендации по безопасности

Объекты Popen

Вспомогательные средства Popen для Windows

Константы Windows

Устаревший высокоуровневый API

Замена устаревших функций модулем subprocess

Замена подстановки команды оболочки /bin/sh

Замена конвейера оболочки

Замена os.system()

Замена семейства функций os.spawn

Замена os.popen(), os.popen2(), os.popen3()

Замена функций модуля popen2

Устаревшие функции вызова оболочки

Примечания

Поведение при тайм-ауте

Преобразование последовательности аргументов в строку в Windows

Отключение использования vfork() или posix_spawn()

Замена `os.system()`

Замена семейства функций `os.spawn`

Замена `os.popen()`, `os.popen2()`, `os.popen3()`

Замена функций модуля `popen2`

Отключение использования `vfork()` или `posix_spawn()`