{
    "mode": "pydoc",
    "parameter": "subprocess",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/pydoc/subprocess/json",
    "generated": "2026-06-02T15:47:46Z",
    "sections": {
        "NAME": {
            "content": "subprocess - Subprocesses with accessible I/O streams\n",
            "subsections": []
        },
        "MODULE REFERENCE": {
            "content": "https://docs.python.org/3.10/library/subprocess.html\n\nThe following documentation is automatically generated from the Python\nsource files.  It may be incomplete, incorrect or include features that\nare considered implementation detail and may vary between Python\nimplementations.  When in doubt, consult the module reference at the\nlocation listed above.\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "This module allows you to spawn processes, connect to their\ninput/output/error pipes, and obtain their return codes.\n\nFor a complete description of this module see the Python documentation.\n\nMain API\n========",
            "subsections": [
                {
                    "name": "run",
                    "content": "CompletedProcess instance.\nPopen(...): A class for flexibly executing a command in a new process\n\nConstants\n---------\nDEVNULL: Special value that indicates that os.devnull should be used\nPIPE:    Special value that indicates a pipe should be created\nSTDOUT:  Special value that indicates that stderr should go to stdout\n\n\nOlder API\n========="
                },
                {
                    "name": "call",
                    "content": "the return code."
                },
                {
                    "name": "check_call",
                    "content": "if return code is not 0"
                },
                {
                    "name": "check_output",
                    "content": "stdout instead of a return code"
                },
                {
                    "name": "getoutput",
                    "content": "then returns the output"
                },
                {
                    "name": "getstatusoutput",
                    "content": "then returns a (exitcode, output) tuple\n"
                }
            ]
        },
        "CLASSES": {
            "content": "builtins.Exception(builtins.BaseException)\nSubprocessError\nCalledProcessError\nTimeoutExpired\nbuiltins.object\nCompletedProcess\nPopen\n",
            "subsections": [
                {
                    "name": "class CalledProcessError",
                    "content": "|  CalledProcessError(returncode, cmd, output=None, stderr=None)\n|\n|  Raised when run() is called with check=True and the process\n|  returns a non-zero exit status.\n|\n|  Attributes:\n|    cmd, returncode, stdout, stderr, output\n|\n|  Method resolution order:\n|      CalledProcessError\n|      SubprocessError\n|      builtins.Exception\n|      builtins.BaseException\n|      builtins.object\n|\n|  Methods defined here:\n|\n|  init(self, returncode, cmd, output=None, stderr=None)\n|      Initialize self.  See help(type(self)) for accurate signature.\n|\n|  str(self)\n|      Return str(self).\n|\n|  ----------------------------------------------------------------------\n|  Data descriptors defined here:\n|\n|  stdout\n|      Alias for output attribute, to match stderr\n|\n|  ----------------------------------------------------------------------\n|  Data descriptors inherited from SubprocessError:\n|\n|  weakref\n|      list of weak references to the object (if defined)\n|\n|  ----------------------------------------------------------------------\n|  Static methods inherited from builtins.Exception:\n|\n|  new(*args, kwargs) from builtins.type\n|      Create and return a new object.  See help(type) for accurate signature.\n|\n|  ----------------------------------------------------------------------\n|  Methods inherited from builtins.BaseException:\n|\n|  delattr(self, name, /)\n|      Implement delattr(self, name).\n|\n|  getattribute(self, name, /)\n|      Return getattr(self, name).\n|\n|  reduce(...)\n|      Helper for pickle.\n|\n|  repr(self, /)\n|      Return repr(self).\n|\n|  setattr(self, name, value, /)\n|      Implement setattr(self, name, value).\n|\n|  setstate(...)\n|\n|  withtraceback(...)\n|      Exception.withtraceback(tb) --\n|      set self.traceback to tb and return self.\n|\n|  ----------------------------------------------------------------------\n|  Data descriptors inherited from builtins.BaseException:\n|\n|  cause\n|      exception cause\n|\n|  context\n|      exception context\n|\n|  dict\n|\n|  suppresscontext\n|\n|  traceback\n|\n|  args\n"
                },
                {
                    "name": "class CompletedProcess",
                    "content": "|  CompletedProcess(args, returncode, stdout=None, stderr=None)\n|\n|  A process that has finished running.\n|\n|  This is returned by run().\n|\n|  Attributes:\n|    args: The list or str args passed to run().\n|    returncode: The exit code of the process, negative for signals.\n|    stdout: The standard output (None if not captured).\n|    stderr: The standard error (None if not captured).\n|\n|  Methods defined here:\n|\n|  init(self, args, returncode, stdout=None, stderr=None)\n|      Initialize self.  See help(type(self)) for accurate signature.\n|\n|  repr(self)\n|      Return repr(self).\n|\n|  checkreturncode(self)\n|      Raise CalledProcessError if the exit code is non-zero.\n|\n|  ----------------------------------------------------------------------\n|  Class methods defined here:\n|\n|  classgetitem = GenericAlias(...) from builtins.type\n|      Represent a PEP 585 generic type\n|\n|      E.g. for t = list[int], t.origin is list and t.args is (int,).\n|\n|  ----------------------------------------------------------------------\n|  Data descriptors defined here:\n|\n|  dict\n|      dictionary for instance variables (if defined)\n|\n|  weakref\n|      list of weak references to the object (if defined)\n"
                },
                {
                    "name": "class Popen",
                    "content": "|  Popen(args, bufsize=-1, executable=None, stdin=None, stdout=None, stderr=None, preexecfn=None, closefds=True, shell=False, cwd=None, env=None, universalnewlines=None, startupinfo=None, creationflags=0, restoresignals=True, startnewsession=False, passfds=(), *, user=None, group=None, extragroups=None, encoding=None, errors=None, text=None, umask=-1, pipesize=-1)\n|\n|  Execute a child program in a new process.\n|\n|  For a complete description of the arguments see the Python documentation.\n|\n|  Arguments:\n|    args: A string, or a sequence of program arguments.\n|\n|    bufsize: supplied as the buffering argument to the open() function when\n|        creating the stdin/stdout/stderr pipe file objects\n|\n|    executable: A replacement program to execute.\n|\n|    stdin, stdout and stderr: These specify the executed programs' standard\n|        input, standard output and standard error file handles, respectively.\n|\n|    preexecfn: (POSIX only) An object to be called in the child process\n|        just before the child is executed.\n|\n|    closefds: Controls closing or inheriting of file descriptors.\n|\n|    shell: If true, the command will be executed through the shell.\n|\n|    cwd: Sets the current directory before the child is executed.\n|\n|    env: Defines the environment variables for the new process.\n|\n|    text: If true, decode stdin, stdout and stderr using the given encoding\n|        (if set) or the system default otherwise.\n|\n|    universalnewlines: Alias of text, provided for backwards compatibility.\n|\n|    startupinfo and creationflags (Windows only)\n|\n|    restoresignals (POSIX only)\n|\n|    startnewsession (POSIX only)\n|\n|    group (POSIX only)\n|\n|    extragroups (POSIX only)\n|\n|    user (POSIX only)\n|\n|    umask (POSIX only)\n|\n|    passfds (POSIX only)\n|\n|    encoding and errors: Text mode encoding and error handling to use for\n|        file objects stdin, stdout and stderr.\n|\n|  Attributes:\n|      stdin, stdout, stderr, pid, returncode\n|\n|  Methods defined here:\n|\n|  del(self, maxsize=9223372036854775807, warn=<built-in function warn>)\n|\n|  enter(self)\n|\n|  exit(self, exctype, value, traceback)\n|\n|  init(self, args, bufsize=-1, executable=None, stdin=None, stdout=None, stderr=None, preexecfn=None, closefds=True, shell=False, cwd=None, env=None, universalnewlines=None, startupinfo=None, creationflags=0, restoresignals=True, startnewsession=False, passfds=(), *, user=None, group=None, extragroups=None, encoding=None, errors=None, text=None, umask=-1, pipesize=-1)\n|      Create new Popen instance.\n|\n|  repr(self)\n|      Return repr(self).\n|\n|  communicate(self, input=None, timeout=None)\n|      Interact with process: Send data to stdin and close it.\n|      Read data from stdout and stderr, until end-of-file is\n|      reached.  Wait for process to terminate.\n|\n|      The optional \"input\" argument should be data to be sent to the\n|      child process, or None, if no data should be sent to the child.\n|      communicate() returns a tuple (stdout, stderr).\n|\n|      By default, all communication is in bytes, and therefore any\n|      \"input\" should be bytes, and the (stdout, stderr) will be bytes.\n|      If in text mode (indicated by self.textmode), any \"input\" should\n|      be a string, and (stdout, stderr) will be strings decoded\n|      according to locale encoding, or by \"encoding\" if set. Text mode\n|      is triggered by setting any of text, encoding, errors or\n|      universalnewlines.\n|\n|  kill(self)\n|      Kill the process with SIGKILL\n|\n|  poll(self)\n|      Check if child process has terminated. Set and return returncode\n|      attribute.\n|\n|  sendsignal(self, sig)\n|      Send a signal to the process.\n|\n|  terminate(self)\n|      Terminate the process with SIGTERM\n|\n|  wait(self, timeout=None)\n|      Wait for child process to terminate; returns self.returncode.\n|\n|  ----------------------------------------------------------------------\n|  Class methods defined here:\n|\n|  classgetitem = GenericAlias(...) from builtins.type\n|      Represent a PEP 585 generic type\n|\n|      E.g. for t = list[int], t.origin is list and t.args is (int,).\n|\n|  ----------------------------------------------------------------------\n|  Data descriptors defined here:\n|\n|  dict\n|      dictionary for instance variables (if defined)\n|\n|  weakref\n|      list of weak references to the object (if defined)\n|\n|  universalnewlines\n"
                },
                {
                    "name": "class SubprocessError",
                    "content": "|  # Exception classes used by this module.\n|\n|  Method resolution order:\n|      SubprocessError\n|      builtins.Exception\n|      builtins.BaseException\n|      builtins.object\n|\n|  Data descriptors defined here:\n|\n|  weakref\n|      list of weak references to the object (if defined)\n|\n|  ----------------------------------------------------------------------\n|  Methods inherited from builtins.Exception:\n|\n|  init(self, /, *args, kwargs)\n|      Initialize self.  See help(type(self)) for accurate signature.\n|\n|  ----------------------------------------------------------------------\n|  Static methods inherited from builtins.Exception:\n|\n|  new(*args, kwargs) from builtins.type\n|      Create and return a new object.  See help(type) for accurate signature.\n|\n|  ----------------------------------------------------------------------\n|  Methods inherited from builtins.BaseException:\n|\n|  delattr(self, name, /)\n|      Implement delattr(self, name).\n|\n|  getattribute(self, name, /)\n|      Return getattr(self, name).\n|\n|  reduce(...)\n|      Helper for pickle.\n|\n|  repr(self, /)\n|      Return repr(self).\n|\n|  setattr(self, name, value, /)\n|      Implement setattr(self, name, value).\n|\n|  setstate(...)\n|\n|  str(self, /)\n|      Return str(self).\n|\n|  withtraceback(...)\n|      Exception.withtraceback(tb) --\n|      set self.traceback to tb and return self.\n|\n|  ----------------------------------------------------------------------\n|  Data descriptors inherited from builtins.BaseException:\n|\n|  cause\n|      exception cause\n|\n|  context\n|      exception context\n|\n|  dict\n|\n|  suppresscontext\n|\n|  traceback\n|\n|  args\n"
                },
                {
                    "name": "class TimeoutExpired",
                    "content": "|  TimeoutExpired(cmd, timeout, output=None, stderr=None)\n|\n|  This exception is raised when the timeout expires while waiting for a\n|  child process.\n|\n|  Attributes:\n|      cmd, output, stdout, stderr, timeout\n|\n|  Method resolution order:\n|      TimeoutExpired\n|      SubprocessError\n|      builtins.Exception\n|      builtins.BaseException\n|      builtins.object\n|\n|  Methods defined here:\n|\n|  init(self, cmd, timeout, output=None, stderr=None)\n|      Initialize self.  See help(type(self)) for accurate signature.\n|\n|  str(self)\n|      Return str(self).\n|\n|  ----------------------------------------------------------------------\n|  Data descriptors defined here:\n|\n|  stdout\n|\n|  ----------------------------------------------------------------------\n|  Data descriptors inherited from SubprocessError:\n|\n|  weakref\n|      list of weak references to the object (if defined)\n|\n|  ----------------------------------------------------------------------\n|  Static methods inherited from builtins.Exception:\n|\n|  new(*args, kwargs) from builtins.type\n|      Create and return a new object.  See help(type) for accurate signature.\n|\n|  ----------------------------------------------------------------------\n|  Methods inherited from builtins.BaseException:\n|\n|  delattr(self, name, /)\n|      Implement delattr(self, name).\n|\n|  getattribute(self, name, /)\n|      Return getattr(self, name).\n|\n|  reduce(...)\n|      Helper for pickle.\n|\n|  repr(self, /)\n|      Return repr(self).\n|\n|  setattr(self, name, value, /)\n|      Implement setattr(self, name, value).\n|\n|  setstate(...)\n|\n|  withtraceback(...)\n|      Exception.withtraceback(tb) --\n|      set self.traceback to tb and return self.\n|\n|  ----------------------------------------------------------------------\n|  Data descriptors inherited from builtins.BaseException:\n|\n|  cause\n|      exception cause\n|\n|  context\n|      exception context\n|\n|  dict\n|\n|  suppresscontext\n|\n|  traceback\n|\n|  args\n"
                }
            ]
        },
        "FUNCTIONS": {
            "content": "",
            "subsections": [
                {
                    "name": "call",
                    "content": "Run command with arguments.  Wait for command to complete or\ntimeout, then return the returncode attribute.\n\nThe arguments are the same as for the Popen constructor.  Example:\n\nretcode = call([\"ls\", \"-l\"])\n"
                },
                {
                    "name": "check_call",
                    "content": "Run command with arguments.  Wait for command to complete.  If\nthe exit code was zero then return, otherwise raise\nCalledProcessError.  The CalledProcessError object will have the\nreturn code in the returncode attribute.\n\nThe arguments are the same as for the call function.  Example:\n\ncheckcall([\"ls\", \"-l\"])\n"
                },
                {
                    "name": "check_output",
                    "content": "Run command with arguments and return its output.\n\nIf the exit code was non-zero it raises a CalledProcessError.  The\nCalledProcessError object will have the return code in the returncode\nattribute and output in the output attribute.\n\nThe arguments are the same as for the Popen constructor.  Example:\n\n>>> checkoutput([\"ls\", \"-l\", \"/dev/null\"])\nb'crw-rw-rw- 1 root root 1, 3 Oct 18  2007 /dev/null\\n'\n\nThe stdout argument is not allowed as it is used internally.\nTo capture standard error in the result, use stderr=STDOUT.\n\n>>> checkoutput([\"/bin/sh\", \"-c\",\n...               \"ls -l nonexistentfile ; exit 0\"],\n...              stderr=STDOUT)\nb'ls: nonexistentfile: No such file or directory\\n'\n\nThere is an additional optional argument, \"input\", allowing you to\npass a string to the subprocess's stdin.  If you use this argument\nyou may not also use the Popen constructor's \"stdin\" argument, as\nit too will be used internally.  Example:\n\n>>> checkoutput([\"sed\", \"-e\", \"s/foo/bar/\"],\n...              input=b\"when in the course of fooman events\\n\")\nb'when in the course of barman events\\n'\n\nBy default, all communication is in bytes, and therefore any \"input\"\nshould be bytes, and the return value will be bytes.  If in text mode,\nany \"input\" should be a string, and the return value will be a string\ndecoded according to locale encoding, or by \"encoding\" if set. Text mode\nis triggered by setting any of text, encoding, errors or universalnewlines.\n"
                },
                {
                    "name": "getoutput",
                    "content": "Return output (stdout or stderr) of executing cmd in a shell.\n\nLike getstatusoutput(), except the exit status is ignored and the return\nvalue is a string containing the command's output.  Example:\n\n>>> import subprocess\n>>> subprocess.getoutput('ls /bin/ls')\n'/bin/ls'\n"
                },
                {
                    "name": "getstatusoutput",
                    "content": "Return (exitcode, output) of executing cmd in a shell.\n\nExecute the string 'cmd' in a shell with 'checkoutput' and\nreturn a 2-tuple (status, output). The locale encoding is used\nto decode the output and process newlines.\n\nA trailing newline is stripped from the output.\nThe exit status for the command can be interpreted\naccording to the rules for the function 'wait'. Example:\n\n>>> import subprocess\n>>> subprocess.getstatusoutput('ls /bin/ls')\n(0, '/bin/ls')\n>>> subprocess.getstatusoutput('cat /bin/junk')\n(1, 'cat: /bin/junk: No such file or directory')\n>>> subprocess.getstatusoutput('/bin/junk')\n(127, 'sh: /bin/junk: not found')\n>>> subprocess.getstatusoutput('/bin/kill $$')\n(-15, '')\n"
                },
                {
                    "name": "run",
                    "content": "Run command with arguments and return a CompletedProcess instance.\n\nThe returned instance will have attributes args, returncode, stdout and\nstderr. By default, stdout and stderr are not captured, and those attributes\nwill be None. Pass stdout=PIPE and/or stderr=PIPE in order to capture them,\nor pass captureoutput=True to capture both.\n\nIf check is True and the exit code was non-zero, it raises a\nCalledProcessError. The CalledProcessError object will have the return code\nin the returncode attribute, and output & stderr attributes if those streams\nwere captured.\n\nIf timeout is given, and the process takes too long, a TimeoutExpired\nexception will be raised.\n\nThere is an optional argument \"input\", allowing you to\npass bytes or a string to the subprocess's stdin.  If you use this argument\nyou may not also use the Popen constructor's \"stdin\" argument, as\nit will be used internally.\n\nBy default, all communication is in bytes, and therefore any \"input\" should\nbe bytes, and the stdout and stderr will be bytes. If in text mode, any\n\"input\" should be a string, and stdout and stderr will be strings decoded\naccording to locale encoding, or by \"encoding\" if set. Text mode is\ntriggered by setting any of text, encoding, errors or universalnewlines.\n\nThe other arguments are the same as for the Popen constructor.\n"
                }
            ]
        },
        "DATA": {
            "content": "DEVNULL = -3\nPIPE = -1\nSTDOUT = -2\nall = ['Popen', 'PIPE', 'STDOUT', 'call', 'checkcall', 'getstatus...\n",
            "subsections": []
        },
        "FILE": {
            "content": "/usr/lib/python3.10/subprocess.py\n\n",
            "subsections": []
        }
    },
    "summary": "subprocess - Subprocesses with accessible I/O streams",
    "flags": [],
    "examples": [],
    "see_also": []
}