Python Embeddable Package 使用指南

前言

Python Embeddable Package 是 Python 官方提供的一种轻量级 Python 分发方式，特别适合以下场景：

需要便携式的 Python 环境（无需安装）
开发小型工具或应用程序
在受限环境中部署 Python 应用
快速搭建临时 Python 环境

本文将详细介绍如何正确使用 Python embeddable package，特别是如何启用第三方库支持。

什么是 Python Embeddable Package？

Python Embeddable Package 是一个精简版的 Python 发行版，具有以下特点：

体积小：仅包含运行 Python 所需的核心文件
免安装：解压即可使用
便携：可以放在 U 盘或任何目录中
独立：不影响系统已有的 Python 安装

但是，默认情况下，embeddable package 不支持第三方库。这就是为什么很多人下载后无法使用 pip 的原因。

下载 Python Embeddable Package

1. 访问官网

前往 Python 官方下载页面：

https://www.python.org/downloads/windows/

2. 选择版本

向下滚动找到 “Embeddable package” 部分，下载对应版本的压缩包。

例如：python-3.13.13-embed-amd64.zip

3. 解压文件

将下载的 ZIP 文件解压到任意目录，例如：

C:\tools\python-3.13.13-embed-amd64\

关键步骤：修改配置文件（最重要！）

这是最关键的一步，很多人在这一步出错导致后续无法使用 pip。

第一步：修改 python313._pth 文件

在运行 get-pip.py 之前，必须先告诉 Python 允许加载第三方库。

进入你的 Python 文件夹：
```
python-3.13.13-embed-amd64\
```
找到名为 python313._pth 的文件：
- 文件名中的数字可能随版本变化（如 python311._pth、python312._pth 等）
- 只要是 .pth 结尾的文件即可
用记事本或代码编辑器打开它
修改配置：

找到包含 import site 的那一行（通常前面有个 # 号，表示被注释掉了）。

修改前：
```
#import site
```
修改后：
```
import site
```
去掉行首的 # 号，保存并关闭文件。

为什么要这样做？

site 模块负责处理 .pth 文件和添加 site-packages 目录到 sys.path
默认情况下，embeddable package 禁用了 site 模块以保持最小化
不启用 site 模块，pip 就无法正常工作

第二步：安装 pip

现在可以安装 pip 了：

1. 下载 get-pip.py

从官方获取安装脚本：

curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py

或者手动下载：

https://bootstrap.pypa.io/get-pip.py

2. 运行安装脚本

在 Python 目录下打开命令行，执行：

python.exe get-pip.py

3. 验证安装

检查 pip 是否安装成功：

python.exe -m pip --version

第三步：配置环境变量（可选但推荐）

为了方便使用，可以将 Python 添加到环境变量：

Windows 系统

右键点击”此电脑” → “属性” → “高级系统设置”
点击”环境变量”
在”系统变量”中找到 Path，点击”编辑”
添加 Python 目录路径，例如：
```
C:\tools\python-3.13.13-embed-amd64\
```
确定保存

验证

打开新的命令行窗口，输入：

python --version
pip --version

第四步：安装第三方库

现在可以正常使用 pip 安装第三方库了：

# 安装单个包
pip install requests

# 安装多个包
pip install numpy pandas matplotlib

# 从 requirements.txt 安装
pip install -r requirements.txt

完整的目录结构

安装完成后，你的目录结构应该类似这样：

python-3.13.13-embed-amd64\
├── python313._pth          # 已修改，启用 import site
├── python313.dll           # Python 核心库
├── python.exe              # Python 可执行文件
├── get-pip.py              # pip 安装脚本（可删除）
├── Lib\
│   └── site-packages\      # 第三方库安装位置
│       ├── pip\
│       └── ...
└── Scripts\
    └── pip.exe             # pip 命令

常见问题及解决方案

问题 1：pip 安装失败，提示找不到 module ‘site’

原因：没有正确修改 python313._pth 文件

解决：确保 import site 前面的 # 已被移除

问题 2：pip 命令不可用

原因：环境变量未配置

解决：

方法 1：使用完整路径 python.exe -m pip install <package>
方法 2：将 Python 目录添加到 PATH 环境变量

问题 3：第三方库安装后找不到

原因：库可能被安装到了错误的目录

解决：

# 查看 site-packages 位置
python.exe -c "import site; print(site.getsitepackages())"

问题 4：升级 pip 失败

解决：

python.exe -m pip install --upgrade pip

最佳实践

1. 虚拟环境

虽然 embeddable package 本身已经很轻量，但你仍然可以使用虚拟环境来隔离项目依赖：

# 创建虚拟环境
python.exe -m venv myenv

# 激活虚拟环境
myenv\Scripts\activate

# 安装依赖
pip install <package>

2. 打包分发

如果你想将 Python 应用分发给其他人：

将整个 Python 目录与应用一起打包
确保 python313._pth 文件已正确配置
提供一个批处理脚本来启动应用

3. 更新 Python 版本

当需要升级到新版本时：

下载新的 embeddable package
复制旧的 Lib/site-packages 到新目录（可选）
重新配置 pythonXX._pth 文件
重新安装必要的依赖

总结

Python Embeddable Package 提供了一种便捷的 Python 部署方式。记住关键点：

必须修改 python313._pth 文件，启用 import site
使用 get-pip.py 安装 pip
根据需要配置环境变量
正常安装和使用第三方库

通过以上步骤，你就可以在任何地方使用一个完全功能的 Python 环境了！

前言