当前位置：首页 > news >正文

subprocess.run函数介绍

news 2026/7/24 23:30:58

前言

subprocess.run 是 Python 3.5 引入的函数，也是目前官方最推荐的用于执行外部命令（如 Shell 命令、系统脚本、其他程序）的方法。

官方文档明确建议：在大多数情况下，应该优先使用 subprocess.run()，而不是旧的 os.system、subprocess.Popen 或subprocess.check_output。它就像一个“全能瑞士军刀”，功能强大且用法灵活。

示例

importsubprocessdefrun_hive_query(cmd):try:# 执行命令，捕获输出，转为文本，并要求失败时报错result=subprocess.run(cmd,capture_output=True,text=True,check=True,timeout=3600# 设置 1 小时超时)# 如果成功，返回标准输出returnresult.stdout.strip()exceptsubprocess.CalledProcessErrorase:# 如果 check=True 触发了异常，可以分别拿到 stdout 和 stderrerror_msg=e.stderr.strip()ife.stderrelse"未知错误"raiseException(f"命令执行失败 (返回码{e.returncode}):{error_msg}")exceptsubprocess.TimeoutExpiredase:raiseException(f"命令执行超时！")

核心参数详解
subprocess.run 之所以全能，是因为它有几个非常实用的参数：

1.capture_output=True: 同时捕获标准输出（stdout）和标准错误（stderr）。（Python 3.7+ 引入，以前的写法是stdout=subprocess.PIPE,stderr=subprocess.PIPE）。
2.text=True (或 encoding=‘utf-8’): 将输入/输出作为字符串处理，而不是字节（bytes）。
3.check=True: 非常重要！默认情况下，run 遇到命令执行失败（返回码非0）不会报错，只会默默返回一个非0的 returncode。如果加上 check=True，一旦命令失败，它会自动抛出 subprocess.CalledProcessError 异常（这就和 check_output 的行为一样了）。
4.timeout=N: 设置超时时间（秒）。如果命令执行超过 N 秒还没结束，会抛出TimeoutExpired 异常。防止程序卡死。
5.shell=True: 允许你直接传入一个完整的字符串命令（比如 “ls -l | grep txt”），而不是列表。警告：除非必要，尽量少用，如果字符串里包含用户输入，会有严重的安全漏洞（Shell 注入）。

核心返回值：CompletedProcess 对象
subprocess.run 执行完毕后，会返回一个 CompletedProcess 对象。这个对象包含了命令执行的所有关键信息：

result.returncode: 退出状态码（0 通常表示成功，非 0 表示失败）。
result.stdout: 标准输出的内容（需要配合 capture_output=True 使用）。
result.stderr: 标准错误的内容（需要配合 capture_output=True 使用）。
result.args: 你原本传递进去的命令

subprocess.check_output和subprocess.run的区别

run 是 Python 3.5 之后引入的“全能瑞士军刀”，而 check_output 是一个专门为了“获取输出”而存在的快捷函数。

以下是具体的区别对比：

返回值不同 (最直观的区别)
subprocess.run：返回一个 CompletedProcess 对象。这个对象包含了命令执行的所有信息，比如返回码 (returncode)、标准输出 (stdout)、标准错误 (stderr)。你需要通过 .stdout 属性才能拿到具体的输出内容。
subprocess.check_output：直接返回命令的标准输出内容（字符串或字节串）。
默认的错误处理方式不同
subprocess.run：默认情况下，如果外部命令执行失败（返回码非 0），它不会报错，而是正常返回一个 CompletedProcess 对象，只是里面的 returncode 不是 0。如果你想让它报错，必须手动加上 check=True 参数。
subprocess.check_output：顾名思义带有 check，如果命令执行失败，它一定会抛出 subprocess.CalledProcessError 异常。

importsubprocess# 直接拿到字符串结果，如果失败会自动抛出异常result_text=subprocess.check_output(["echo","hello"],text=True)print(result_text)# 需要指定 capture_output=True 才会捕获输出# 需要指定 check=True 才会像 check_output 一样在失败时报错# 最后需要加上 .stdout 才能拿到具体的文本result=subprocess.run(["echo","hello"],capture_output=True,text=True,check=True)result_text=result.stdoutprint(result_text)