Python免安装版运行脚本报错ModuleNotFoundError怎么办

一、免安装版的特殊性与报错根源

在 Windows 环境下，许多开发者为了方便分发软件、制作绿色工具箱或避免在客户电脑上产生安装污染，会从 Python 官方网站下载类似 python-3.10.11-embed-amd64.zip 的免安装压缩包。解压后即可直接双击 python.exe 运行，非常轻便。

然而，当尝试用它运行一个依赖第三方库（例如 requests、pandas、openpyxl）的脚本时，控制台几乎百分之百会抛出如下错误：

Traceback (most recent call last):
  File "main.py", line 1, in <module>
    import requests
ModuleNotFoundError: No module named 'requests'

对于刚接触便携版 Python 的读者而言，最直观的反应通常是“去命令行安装这个库”。但即使在命令行窗口中执行了 pip install requests 并看到安装成功提示，回过头来再次用免安装版运行脚本，依然顽固地提示 ModuleNotFoundError。

这并非 Python 程序损坏，而是由免安装版（Embeddable Package）的底层定位与寻路机制决定的。官方发布免安装包的本意是作为“嵌入到其他 C/C++ 宿主程序内的轻量运行时”，为了保证嵌入宿主时的纯净与安全，官方对该包做了两项硬性限制：

• 默认关闭标准包机制（site-packages）：解压目录下的 python3x._pth（如 python310._pth）是解释器的路径索引文件。在免安装包中，该文件内部的 #import site 默认处于被注释状态。只要未启用 site，Python 启动时就不会主动去寻找 site-packages 文件夹，也不会读取用户级安装目录。
• 完全忽略系统环境变量与注册表：免安装版不会读取操作系统的 PYTHONPATH，也不会读取 Windows 注册表中记录的全局 Python 库路径。它只认 ._pth 文件中明文登记的相对或绝对路径。

二、为什么“明明 pip 安装成功”仍然报错？

许多读者在此处会产生困惑：“我在 CMD 里敲了 pip install，进度条明明跑完了，为什么免安装版还是找不到？”这是一个非常典型的多解释器错位与全局环境变量混淆问题。

在 Windows 系统中，如果你直接在终端中敲下 pip 或 python，系统会顺着全局环境变量 PATH 从前向后匹配。如果电脑曾经安装过标准版 Python、Anaconda，或者触发了 Windows 10/11 自带的应用商店跳转桩（App Execution Alias），终端中的 pip 实际上属于那个全局环境。

结果显而易见：你的依赖库被下载并安装到了全局环境的 C:\Users\用户名\AppData\Local\Programs\Python\... 目录中；而你运行脚本时调用的免安装版解释器（例如 D:\tools\python-embed\python.exe）在自身严格隔离的 sys.path 视野内，根本无法跨越目录看到其他解释器的库。

你可以通过一行简短的代码亲自查看当前免安装版能够搜索的目录路径。在免安装版根目录下打开命令提示符，执行以下命令：

.\python.exe -c "import sys; print('\n'.join(sys.path))"

可以看到，默认状态下其搜索列表仅有打包的基础 zip 和当前根目录，完全没有 site-packages。在这种状态下，任何第三方库自然都会触发 ModuleNotFoundError。

三、完整解决步骤：从配置到验证

要让免安装版恢复对第三方库的支持，并形成一个独立、可随处移动运行的便携环境，请按以下 4 个步骤依次操作。

步骤 1 修改 python3x._pth 配置文件

打开免安装版解压所在的文件夹。你会看到一个以 ._pth 结尾的文件，例如 python310._pth（根据你下载的 Python 大小版本而定，3.9 为 python39._pth，3.11 为 python311._pth）。

使用任意纯文本编辑器（如记事本、VS Code 或 Notepad++）打开该文件。其默认原始内容大致如下：

python310.zip
.

# Uncomment to run site.main() automatically
#import site

我们需要进行两项修改：

1. 删除 #import site 前面的井号 # 和空格，使其成为一行独立的 import site；
2. 在文件中额外新增一行 Lib\site-packages（也可以写为 Lib/site-packages），指定未来第三方模块的安放目录。

修改完成后保存文件。此时该 ._pth 文件的完整内容应为：

python310.zip
.
Lib\site-packages

import site

步骤 2 为免安装版独立安装 pip 工具

免安装包为了极限压缩体积，出厂时不包含 pip 包管理器。我们需要使用 Python 官方维护的独立引导安装脚本 get-pip.py。

1. 通过浏览器访问 Python 官方引导脚本地址 https://bootstrap.pypa.io/get-pip.py，在网页上右键“另存为”，将 get-pip.py 文件直接保存在免安装版的根目录下。
2. 在免安装版的根目录空白处按住 Shift 键并右键，选择“在终端中打开”或“在此处打开 Powershell 窗口”（或打开 CMD 并 cd 到该目录）。
3. 执行如下命令，使用当前免安装目录下的 python.exe 执行引导安装：

.\python.exe get-pip.py --no-warn-script-location

脚本会自动下载并配置匹配该版本的 pip、setuptools 与 wheel。执行完毕后，你会发现免安装目录下自动生成了两个新文件夹：

• Lib/site-packages/：未来所有安装的第三方包都会存放在这里；
• Scripts/：存放 pip.exe 等命令行工具。

步骤 3 使用免安装解释器精准安装所需依赖

有了独立的 pip 之后，切记不要直接在终端输入全局命令 pip install xxx，因为这依然可能触发前文分析的系统全局环境变量错位。

正确的操作规范是：始终以当前免安装目录下的 python.exe 作为唯一入口，通过 -m pip 模块形式执行安装。例如你需要安装 requests 库：

.\python.exe -m pip install requests

由于我们已在 ._pth 中登记了 Lib\site-packages，pip 会精准地将库文件写入免安装目录的 Lib\site-packages\requests 中，绝不污染系统，也不会受到外部干扰。

步骤 4 运行验证与路径核对

安装完成后，我们通过一行命令校验免安装解释器是否能准确找到该模块及其真实的物理落盘路径：

.\python.exe -c "import requests; print('成功加载模块，文件路径：', requests.__file__)"

如果输出的路径明确位于你免安装目录的 Lib\site-packages 下，说明环境已彻底打通。此时运行你的业务脚本：

.\python.exe main.py

之前的 ModuleNotFoundError 将彻底消除，脚本正常执行。

四、深度辨析：不装 pip，直接复制第三方库可行吗？

在实际开发和企业内网离线环境中，经常有开发者提出这样的想法：“免安装版既然只需要找文件，我能不能直接把别人电脑上装好的库文件夹复制粘贴到免安装版目录里，不装 pip 行不行？”

对于需要离线部署的环境，规范可靠的做法是在一台能够联网且环境相同的机器上，使用 pip download 预先下载离线 Wheel 包，再在目标免安装机上进行离线安装：

# 在联网机下载离线依赖包至 wheels 目录
python -m pip download requests -d ./wheels

# 在目标免安装机上通过离线包精准安装
.\python.exe -m pip install --no-index --find-links=./wheels requests

五、总结与免安装环境分发自检清单

将配置好的免安装版打包发送给他人使用，或者放入自动化任务前，建议对照以下自检清单逐一确认，确保其在其他电脑上也能即开即用、无缝运行。

@echo off
rem 切换工作目录至当前 bat 所在路径，防止相对路径偏移
cd /d "%~dp0"

rem 显式使用当前目录的便携解释器运行主脚本
"%~dp0python.exe" main.py

rem 发生错误时暂停控制台，方便查看报错信息
if %errorlevel% neq 0 (
    echo.
    echo 脚本异常退出，错误代码: %errorlevel%
    pause
)