外观
Python 脚本在本机能跑,上线却找不到依赖:解释器与虚拟环境入门
摘要
安装成功,运行却提示找不到模块,常见原因是两条命令使用了不同的 Python。本文面向有编程经验、没有 Python 基础的开发者,从第一段脚本出发,讲清解释器、依赖安装与虚拟环境的对应关系。
1. 场景:安装记录与报错为什么可以同时成立
考虑一个教学场景:你接手日志汇总脚本,在终端执行 pip install requests,看见成功提示,随后运行 python report.py,却得到 ModuleNotFoundError: No module named 'requests'。再次安装仍然没有变化。这不是一句“重新安装 Python”能解释的问题。安装成功说明某个环境中出现了包,运行失败说明当前解释器没有找到它;两件事如果发生在不同环境,就完全不矛盾。
先把故障画成一条身份链:启动命令选择解释器,解释器确定环境与搜索位置,加载才可能取得依赖。 安装成功证明的是某个目标位置已有文件,运行失败描述的是当前进程没取得模块;先对齐两端身份,再讨论包是否损坏。解释器是读取并执行 Python 程序的运行时;Python 是语言,CPython 是主要由 C 实现的解释器。本系列以 CPython 3.14 常规构建为主线,不把实现细节当语言规范。
假设 A、B 都显示同一版本,只有 A 安装了包。现在用 B 执行导入,版本相同会改变结果吗?不会:相同版本没有把 A 的安装目录加入 B 的搜索范围。后面实验只改变启动解释器,保持包名与导入语句不变,让这条身份链给出可检查的判断。终端、编辑器和服务启动器可以各自选解释器,所以要取得正在失败的进程证据。
命令中的 python 只是名称。Shell(命令行解释程序)根据自己的查找规则找到可执行文件;在常见配置中,PATH 环境变量列出候选目录。pip 同样是一个命令名称,并没有语言层面的规则保证它和旁边输入的 python 属于同一安装。Windows 上的启动器、应用执行别名,Linux 上的多个安装目录,以及编辑器设置,都可能改变具体选择。诊断时不猜,直接让运行中的解释器报告身份。
2. 先运行一段真正的 Python 程序
安装来自可信渠道的 CPython 后,在自己的项目目录创建 hello.py。文件内容如下,保存为 UTF-8:
python
# hello.py:Python 用缩进表示代码块。
name = "backend"
if name:
print("hello", name)在该目录运行 python hello.py,预期得到 hello backend。name = ... 把名称绑定到一个字符串对象;字符串是文本数据。if 根据条件决定是否执行后面的代码块;冒号表示代码块即将开始。同一层级保持相同缩进,通常使用四个空格,不混用制表符和空格。print 是标准内置函数,用于把值写到标准输出。函数可以先理解成完成一项工作、接受输入的可调用对象;第五篇再解释它的参数绑定。
不要把交互界面的 >>> 提示符复制进源文件。直接运行 python 通常进入交互模式,输入一行便执行一行,适合快速试验;脚本模式则读取文件。交互环境还保留之前的定义,容易让缺少初始化的片段看似正常。分享代码时应能从新启动的进程运行,不能依赖终端中碰巧已经定义的变量。解释器的交互和脚本调用方式见 Python 3.14 解释器教程。
本系列的代码中常见 if __name__ == "__main__":。现阶段把它理解成启动入口:直接运行文件时调用 main(),被其他文件导入时保留函数定义而不自动执行入口。这里比较的是字符串内容,用 ==。它不是安装依赖的方法,也不会把整个文件隔离成另一环境;模块与入口的完整机制留到第八篇。
3. 从一条启动命令恢复环境身份
先运行以下命令。-c 表示执行后面的短程序,import sys 导入解释器提供的运行信息模块:
powershell
python -c "import sys; print(sys.executable); print(sys.version); print(sys.prefix); print(sys.base_prefix)"
python -m pip --versionsys.executable 给出当前解释器可执行文件的路径,sys.version 给出版本信息。sys.prefix 是当前环境的前缀路径,sys.base_prefix 是创建虚拟环境所依托的基础安装前缀。在常规 venv 环境内两者不同,环境外通常相同。这些属性的定义见 sys 文档。不要把版本字符串相同当成环境相同:两个独立环境可以使用同样版本,但安装完全不同的依赖。
python -m pip 表示让当前这一个 Python 按模块方式运行 pip。它把“谁执行安装”绑定到“谁启动程序”,比独立输入 pip 更容易排除错位。若它报 No module named pip,说明当前环境没有提供 pip,应按该发行版方式准备,而不是切到另一个能执行 pip 的环境后假定问题解决。某些精简或嵌入式发行方式有意不带完整安装工具,本篇常规安装步骤不适用于所有分发形态。
对运行失败的进程还需要知道模块搜索路径。可以临时输出 sys.path,它是解释器用于相关模块搜索的一组位置,不等于操作系统的 PATH。前者帮助 Python 找模块,后者帮助 Shell 找可执行命令。在后续章节中我们会进一步区分内置模块、路径查找器和包路径;现在只需记住,安装位置不在当前进程实际使用的搜索范围内,模块就不会凭“安装过”自动出现。
图表将在阅读到此处时加载…
图里没有把 pip 当成另一个全局依赖仓库。依赖最终存在文件系统和安装元数据中,解释器通过自己的环境与导入机制使用它们。安装动作也可能受用户安装、目标目录等参数影响;因此确认解释器相同之后,仍应核对实际安装位置,而不能停止在命令形式一致。
4. 用虚拟环境把项目依赖隔开
virtual environment(虚拟环境)是一套建立在基础 Python 安装之上的项目运行环境。标准库 venv 为它准备环境配置、可执行入口和独立的第三方包安装位置,通常仍利用基础安装的标准库。它没有模拟整个操作系统,也不是虚拟机;它主要解决 Python 依赖相互污染的问题。默认的常规 venv 不开放基础环境的 site-packages,显式选择 --system-site-packages 会改变边界。具体行为以 venv 文档为准。
Windows PowerShell 的常规步骤如下;先确认这里的 python 确实是准备使用的基础解释器:
powershell
python -m venv .venv
.\.venv\Scripts\python.exe -m pip --version
.\.venv\Scripts\python.exe hello.pyLinux 或 macOS 使用对应入口:
bash
python3 -m venv .venv
./.venv/bin/python -m pip --version
./.venv/bin/python hello.py这些命令不依赖激活脚本。activation(激活)通常修改当前 Shell 的 PATH 等状态,让短名称 python 优先指向虚拟环境;它是操作便利,不是虚拟环境存在的必要条件。后台服务、定时任务和持续集成中,直接使用虚拟环境解释器路径往往更明确。若 PowerShell 的脚本执行策略阻止激活,也可以照上面的方式执行,不必为了一个教程修改整台机器的执行策略。 可进一步阅读systemd启动就绪与时间基础:服务启动环境可能不同于交互Shell。
项目需要第三方库时,用该环境的解释器安装,例如 .\.venv\Scripts\python.exe -m pip install requests。这是安装形式示意,本篇最小实验不需要 requests,也不依赖网络。实际项目还要选定和记录版本,第十四篇会解释依赖约束与锁定。不要把一个项目的 .venv 当成便携安装目录随意搬到另一机器:环境中的脚本和配置可能含绝对路径,基础安装也未必存在。更可靠的交付方式是记录 Python 版本和依赖,然后在目标机器重建。
5. 最小实验:确认正在运行谁,再观察缺失模块
运行前先列三个预测:A 安装成功;B 导入仍失败;同一导入交给 A 才成功。跟踪的不是终端提示符,而是 A/B 的 pyvenv.cfg → prefix → site → sys.path → 模块 spec。其中一环若与预测不同,就在那一环继续查,而不是再安装一遍。下面先做缺失模块基线,再让本地 wheel 验证这三个结果。
完整文件为 01_environment.py,只使用标准库。先用不存在的模块建立诊断基线,再创建 A/B 环境并真实安装本地教学包,以同一导入验证故障及修复。
python
"""识别实际解释器,不依赖第三方包。"""
import importlib.util
import json
import sys
import argparse
import base64
import hashlib
from pathlib import Path
import subprocess
from tempfile import TemporaryDirectory
from zipfile import ZipFile
def main():
parser = argparse.ArgumentParser()
parser.add_argument("--bootstrap-python", default=sys.executable,
help="带 venv/ensurepip 的完整 CPython 可执行文件")
args = parser.parse_args()
print("executable:", sys.executable)
print("version:", sys.version.split()[0])
print("isolated:", sys.prefix != sys.base_prefix)
# 使用不存在的教学模块,复现“安装环境与运行环境不匹配”的症状。
module = "python_series_missing_demo"
assert importlib.util.find_spec(module) is None
try:
__import__(module)
except ModuleNotFoundError as exc:
print("missing:", exc.name)
print(json.dumps({"ready": True}, ensure_ascii=False))
# 构造最小本地 wheel,pip 只读取本地文件,不访问网络。
with TemporaryDirectory() as directory:
root = Path(directory)
wheel = root / "series_demo-1.0-py3-none-any.whl"
info = "series_demo-1.0.dist-info"
files = {
"series_demo/__init__.py": "VALUE = 'installed-in-A'\n",
f"{info}/METADATA": "Metadata-Version: 2.1\nName: series-demo\nVersion: 1.0\n",
f"{info}/WHEEL": "Wheel-Version: 1.0\nGenerator: teaching\nRoot-Is-Purelib: true\nTag: py3-none-any\n",
}
records = []
with ZipFile(wheel, "w") as archive:
for filename, content in files.items():
payload = content.encode("utf-8")
digest = base64.urlsafe_b64encode(hashlib.sha256(payload).digest()).rstrip(b"=").decode("ascii")
archive.writestr(filename, payload)
records.append(f"{filename},sha256={digest},{len(payload)}\n")
archive.writestr(f"{info}/RECORD", "".join(records) + f"{info}/RECORD,,\n")
executables = {}
for name in ("A", "B"):
environment = root / name
subprocess.run([args.bootstrap_python, "-m", "venv", str(environment)], check=True)
executable = environment / ("Scripts/python.exe" if sys.platform == "win32" else "bin/python")
executables[name] = executable
subprocess.run([str(executables["A"]), "-m", "pip", "install", "--no-index",
"--disable-pip-version-check", str(wheel)], check=True,
capture_output=True, text=True)
probe = ("import importlib.util,json,site,sys; "
"print(json.dumps({'prefix':sys.prefix,'base':sys.base_prefix,"
"'site':site.getsitepackages(),'path':sys.path,"
"'found':importlib.util.find_spec('series_demo') is not None}))")
for name, executable in executables.items():
evidence = json.loads(subprocess.check_output([str(executable), "-c", probe], text=True))
assert evidence["found"] == (name == "A")
assert evidence["prefix"] != evidence["base"]
assert any(entry in evidence["path"] for entry in evidence["site"])
configuration = (root / name / "pyvenv.cfg").read_text(encoding="utf-8")
home = next(line for line in configuration.splitlines() if line.startswith("home ="))
print(name, "configuration:", home, "prefix:", evidence["prefix"])
print(name, "site:", evidence["site"])
print(name, "found:", evidence["found"], "site in sys.path:", True)
wrong = subprocess.run([str(executables["B"]), "-c", "import series_demo"],
capture_output=True, text=True)
assert wrong.returncode != 0 and "ModuleNotFoundError" in wrong.stderr
repaired = subprocess.check_output([str(executables["A"]), "-c",
"import series_demo; print(series_demo.VALUE)"], text=True)
assert repaired.strip() == "installed-in-A"
print("repair:", repaired.strip())
if __name__ == "__main__":
main()从仓库根目录执行 python docs/python/examples/01_environment.py,再用项目虚拟环境的 Python 运行同一文件。预期前者和后者的 executable 不同;常规环境外 isolated 为 False,venv 内为 True。两次都应打印 missing: python_series_missing_demo 以及 {"ready": true}。路径和版本由运行环境决定,不把它们写成固定输出。try/except 在这里捕获预期异常,让后面的正例继续运行;异常语义会在第七篇完整展开。
反例是“只看到安装命令成功,就认为运行进程一定能导入”;正例是让真正的运行解释器报告身份,用同一入口检查和安装,再验证导入。标准库 JSON 的成功导入只说明基础运行可用,不能证明某个第三方包已安装。find_spec 在此只搜索简单顶层模块;对于带父包的名称,它可能触发父包导入,因此不要把这个 API 普遍理解成完全没有副作用的探测。
6. 把排查顺序固定下来
遇到缺失模块,先定位报错来自哪个进程和启动命令。编辑器终端中运行成功,不能替代服务进程的证据。让服务在启动日志里记录解释器路径和版本,并在必要时记录环境前缀。随后用同一个可执行文件执行 -m pip --version 和 -m pip show 包名,比较安装位置与实际搜索环境。最后再检查依赖名、导入名和文件遮蔽;安装时的 distribution name(分发名称)与代码中的模块名称不总相同,不应机械地把 import 后面的名字复制到安装命令。
有一个容易遗漏的坑:你在 Shell 中激活了环境,但已经运行的服务没有因此改变。激活修改的是当前 Shell,旧进程保留其启动状态;其他终端也不会同步修改。修正服务启动配置后,需要按服务管理方式重启并确认新进程身份。相反,如果环境身份正确而导入仍失败,不要不停重建环境,应检查真实缺失的是顶层依赖,还是该依赖内部又导入的另一个模块。异常中的模块名和完整调用栈能帮助区分。
环境隔离也有明确边界。它不隔离 CPU、内存、网络、系统共享库或数据库;两个项目仍然可能争用同一个端口。依赖含原生扩展时,操作系统、架构、系统库和包构建产物也影响兼容性。venv 能把 Python 包的安装集合分开,却不能保证所有外部资源自动一致。把这些信息加入部署记录,才可能从开发机重现到服务器。
7. 把环境信息做成可交接的运行说明
项目能在自己的终端运行,只完成了交付的一部分。接手者至少需要知道使用哪个 Python 主次版本、入口在哪里、依赖怎样准备、配置从哪里读取。把启动方式写成明确命令,能减少“打开编辑器后按某个按钮”的隐含步骤。例如开发者用 .venv,服务启动器也明确指定 .venv 的解释器,而不是期待它继承某个交互终端的激活状态。
对于第一份日志工具,目录里至少保留源文件与简短运行说明。虚拟环境目录属于可重建产物,通常不提交到源码仓库。不要直接把自己环境中的所有包列表解释成项目真正需要的依赖:其中可能有临时调试工具、其他项目遗留包或未使用的库。正式整理依赖时区分直接使用的包与其间接依赖;第十四篇会详细建立打包和锁定方案,本篇先保证运行入口是唯一而明确的。
一个排查记录应同时包含操作与验证。例如“把服务配置改为指定解释器”只是动作;“新进程报告了预期的可执行路径,并成功导入目标模块”才是验证。再补一次实际任务运行,避免导入成功但其他配置错误。若服务管理器会自动拉起旧配置,或者多个实例同时运行,核对进程标识与时间也很重要,不把另一实例的成功日志当成本次修复证据。
Shell 中的工作目录同样应记录。依赖搜索与读取业务文件是两个问题:第三方库能导入,却打不开 data/events.log,可能只是相对文件路径解析到另一个目录。不要为文件路径问题反复安装包;也不要为导入问题把所有数据目录加入模块搜索范围。把“可执行入口”“模块来源”“业务数据位置”分开记录,能避免互相掩盖。
升级基础 Python 后,不应假设旧虚拟环境继续具有相同兼容性。标准库、解释器 ABI(原生扩展与运行时交互的二进制接口)和第三方轮子支持情况可能变化。更稳妥的方式是在新环境重建依赖,验证入口和关键工作流,然后再更新服务启动配置。没有针对本项目验证之前,不写“升级一定无影响”;具体差异需要对应版本发布说明和依赖支持信息。
如果一台机器安装了多个版本,可以先用可执行文件绝对路径创建环境,消除创建阶段的歧义。之后通过环境自己的解释器启动,避免在每次运行中重新参与全局命令查找。路径里含空格时,PowerShell 使用引号并配合调用操作符 & 执行,例如 & 'C:/Program Files/Python/python.exe' -V。这解决的是 Shell 参数解析,不是 Python 语法;写教程时明确命令属于哪种 Shell,避免把 PowerShell 的写法直接交给 Bash。
还有一种误用是把“能导入”当成“版本符合要求”。同一模块名字可能来自多个不同版本,接口或默认行为有差异。安装元数据、发行版本和模块来源是后续兼容性排查的证据。不要在生产排障时无约束安装最新版本来试错:优先复现已记录环境,确认问题后在隔离环境评估版本调整。这不是为了引入繁琐流程,而是避免修复一个导入错误时产生新的接口变化。
8. 进阶与面试:用关系解释,别背命令
为什么推荐 python -m pip? 因为安装工具在指定解释器中运行,减少命令路径错位;它仍要结合安装参数和目标路径检查。答案不能只有“这样更规范”,需要说明这条命令怎样改变身份选择。
虚拟环境与容器有什么关系? 前者主要隔离项目的 Python 安装环境,后者通过操作系统机制组织进程、文件系统与资源边界。容器里也可以使用虚拟环境;是否需要取决于镜像和部署方式,两者不是互斥开关。初学阶段先建立“环境是依赖归属关系”的模型,不需要先掌握容器才能写 Python。
同一版本为何仍会导入失败? 版本只描述运行时的一部分。同版本的不同环境可以有不同包集合、搜索路径和启动方式。沿“可执行入口—环境—模块搜索—具体报错”提供证据,才是完整回答。接下来把环境问题放下,用这个稳定入口编写日志汇总脚本;以后每次实验都从明确的解释器开始。
把同一身份链迁移到编辑器与定时任务
将终端换成编辑器、定时任务或服务启动器,变化的是“谁选择可执行文件”,后面的环境与搜索链没有变。因此在终端修好的启动命令只是一个正例,还要从实际入口取得 executable 与包来源。第八篇接着回答“文件已经找到,为什么初始化仍失败”,第十四篇回答“怎样把文件可靠安装到目标环境”;它们分别补身份链的加载与交付阶段。
上述增强实验真正创建 A、B 两个虚拟环境,把本地教学 wheel 安装到 A。Wheel 是可安装分发文件;这里只手工生成一个纯 Python 最小包来排除网络、构建工具与下载失败的干扰,正式项目的构建见第十四篇。A 的 pip 成功之后,B 的真实 import series_demo 仍失败;改用 A 的可执行文件运行同一导入才成功。这三个结果共同支持“运行身份不匹配”,比单独探测一个不存在的名字有说服力。
观察链从 A/B 的 pyvenv.cfg 中 home 指向基础安装开始,经环境前缀得到项目环境位置,再观察 site.getsitepackages() 列出的包目录是否出现在 sys.path 中,最后查询模块 spec。site 是管理站点包路径的标准库模块,sys.path 是搜索路径列表。它们与 -S、隔离选项等启动设置有关系,不保证所有启动模式都具有同一条路径布局;实验只验证默认完整 CPython 虚拟环境。Python 3.14 将环境前缀设置移到路径初始化,不能把旧版本“必须由 site 设置前缀”的因果关系照搬过来,见sys.prefix 文档。
程序需完整 CPython 的 venv/ensurepip。普通安装直接运行;嵌入版可传 --bootstrap-python 完整安装的python路径,此时打印的主进程版本和 A/B 所用版本应分别记录,不能声称嵌入版自己创建了虚拟环境。实验预期输出 A found: True、B found: False 和 repair: installed-in-A,目录均为临时目录。
独立练习:把教学包只安装到 B,再修复 A 的启动命令,不许修改 sys.path。验收要求保留安装命令、两个前缀、包来源与失败返回码,并证明同一导入由所选环境成功执行。第八篇解释找到模块之后怎样初始化,环境身份与模块加载是两个连续但不同的问题。
一句话总结:依赖属于具体运行环境,定位导入失败先确认真正执行程序的 Python。
- 用
sys.executable和环境前缀识别进程身份,不能只看版本或终端提示。 - 用明确的解释器路径和
-m pip连接安装与运行,虚拟环境无需激活也能使用。 - 记录环境并重建依赖,比复制整个虚拟环境或反复安装更容易复现。
参考:解释器调用、venv、sys。独立示例已在 Windows x64 的 CPython 3.14.0 和 3.13.7 验证通过。完整安装的 3.13.7 还验证了临时 venv 创建、-m pip --version 与环境内运行,均成功,isolated 为 True。3.14.0 使用嵌入版,不以该发行形态验证常规安装与 venv 流程;Linux/macOS 命令未在本机执行。