Python sys：解释器、模块搜索路径与进程参数

sys 提供当前 Python 解释器和进程的状态，包括参数、模块搜索路径、已加载模块、标准流和退出接口。排查“同一段代码在终端、编辑器或 Notebook 中行为不同”，先确认实际解释器与工作目录，再看导入路径；不要先清空 sys.path。

本页以 CPython 3.11 为运行基线。Python 的执行方式由具体实现决定；CPython 通常先将源代码编译为字节码再执行，导入的模块还可能来自原生扩展、内置模块或其他加载器。因此“Python 不编译、总是逐行解释源文件”并不准确。

先确认正在运行哪一个解释器

下面只读取状态，并查询已知标准库模块的规格；它不会安装包或修改搜索路径。

import importlib.util
import os
import sys
import sysconfig

print("executable:", sys.executable)
print("version:", sys.version_info[:3])
print("implementation:", sys.implementation.name)
print("prefix:", sys.prefix)
print("base_prefix:", sys.base_prefix)
print("virtual_environment:", sys.prefix != sys.base_prefix)
print("cwd:", os.getcwd())
print("purelib:", sysconfig.get_path("purelib"))
print("platlib:", sysconfig.get_path("platlib"))
spec = importlib.util.find_spec("pathlib")
assert spec is not None
print("pathlib origin:", spec.origin)
assert sysconfig.get_path("purelib") is not None

sys.executable 通常是当前解释器的绝对路径，但特殊嵌入环境可能为空或 None。运行同一环境中的模块时，可使用该路径配合 -m；例如在诊断中用它运行 pip --version，比猜测终端里另一个 pip 属于哪个环境更可靠。

标准 venv 中，sys.prefix 指向虚拟环境，sys.base_prefix 指向基础解释器安装。虚拟环境仍会使用基础解释器的标准库；基础环境的第三方 site-packages 是否参与搜索，则由 include-system-site-packages 等配置决定，默认创建的 venv 不包含系统第三方包。不能概括成“环境内找不到就自动退回全部系统包”。Python venv 文档

sysconfig.get_path("purelib") 表示当前安装方案中纯 Python 第三方库的安装位置，platlib 表示平台相关库的位置；两者可能相同。它们不是完整搜索列表，也不能仅凭该路径证明某个包确实从那里加载。

sys.argv 是字符串列表

普通脚本启动时，sys.argv[0] 是脚本名称，其余元素才是应用参数。不同启动方式，例如 -c、-m 或交互模式，会改变第 0 项，不能一律当作已经存在的绝对文件路径。

表达式	含义与边界
sys.argv	包含第 0 项的参数列表；每一项是字符串
sys.argv[1:]	应用参数列表，可以为空
sys.argv[1]	第一个应用参数字符串；没有参数时抛出 IndexError
parser.parse_args()	ArgumentParser 实例默认解析 sys.argv[1:]，完成类型与规则检查
parse_args(["--count", "3"])	解析显式列表，不包含程序名；适合测试和 Notebook

例如 python compute.py all 中，第一个应用参数是字符串 "all"，不是脚本路径，更不是一个新的列表。需要选项和错误提示时使用 argparse，不通过手工改全局 sys.argv 配置可复用函数。

sys.path 已经包含默认路径

sys.path 是导入系统使用的路径列表，包含初始化阶段形成的默认路径和后续变更，并非只记录手工追加的“默认路径扩展”。普通文件系统模块的路径查找会使用它；导入过程还涉及 sys.modules 缓存以及 sys.meta_path 中的查找器。

一般启动情形下，脚本目录、当前目录、PYTHONPATH、标准库和由 site 配置的包目录会按初始化规则参与；具体内容取决于启动方式、虚拟环境、._pth 文件及隔离选项。python script.py 通常从脚本目录开始，而 python -m package.module 通常包含当前工作目录。用 -I 等隔离模式时，不能沿用这些普通启动假设。搜索路径初始化

对象	用来回答的问题
sys.path	路径查找器当前可以到哪些路径寻找模块？
sys.modules	哪些模块名称已经映射到加载结果？
sys.meta_path	哪些查找器有机会按名称提供模块规格？
module.__spec__.origin	这个已加载模块的规格记录了什么来源？
module.__file__	如果加载器提供该属性，关联的文件在哪里？内置/命名空间模块未必具有普通文件路径

import 通常先复用 sys.modules 中的对象。因此修改 sys.path 后再次导入同名模块，并不自动切换到另一个版本。find_spec() 也可能复用已加载模块的规格；查询带点的子模块名称时，它还可能导入父包，不能把任意查询都当作无副作用的文件搜索。Python 导入系统

原稿中的 sys.path.clear()、sys.path = [] 会删除现有搜索项，影响尚未导入的标准库和依赖。导入完一个模块后也不需要清空路径。临时追加路径只是排障手段；项目通常应使用正确包结构、从合适位置执行 python -m ...，或在所选环境中安装项目。

如果确实需要诊断指定的本地文件，请使用有明确模块名称的 importlib 加载流程，并理解执行模块代码会产生副作用。不要把当前目录中碰巧叫 json.py、typing.py 的文件误认为标准库；路径顺序和同名文件都是排查重点。

标准流与退出不是普通打印的别名

sys.stdin、sys.stdout、sys.stderr 通常是文本流，分别用于输入、普通输出和诊断。它们可能被编辑器、Notebook 或测试替换，未必有 .buffer、fileno() 等底层接口；无控制台的 pythonw 环境中还可能为空。

下面独立示例把退出行为限制在自己的函数中，验证 finally 会执行：

import sys


def finish(events):
    try:
        sys.exit(3)
    finally:
        events.append("cleanup")


events = []
try:
    finish(events)
except SystemExit as exc:
    assert exc.code == 3
assert events == ["cleanup"]
print("exit raised SystemExit and cleanup ran")

sys.exit() 引发 SystemExit，它可以被捕获，不是立即终止整个进程的系统调用。在线程中使用它通常只结束该线程；在主线程中未被捕获时才按正常退出路径处理。except Exception 不会捕获它。常见退出码约定是 0 成功、非 0 失败，但具体数值的可用范围由操作系统和调用方规定。Python sys 文档

原记录夹入的 os.path.join、os.walk、目录枚举与文件读取属于 os 与文件接口；JSON 文件解析见 json。它们不通过清空 sys.path 获得可用性。包导入失败时，记录解释器、启动方式、工作目录、异常类型和实际模块来源，比反复更换路径更有助于定位原因。