Python 便携版使用教程

下面给你一份**“Python 便携版（Embedded Python）完整使用 & 配置教程”。 这是工程级、可复用**的版本，完全对标 ComfyUI 的做法，你照着走一遍，就能理解 为什么这么做，以后再也不会被 Python 环境坑。

适用对象：

• 想做 便携 AI 工具 / GUI 程序 / 内置 Python 的软件

• 不依赖系统 Python

• 不用 venv / conda

• 可复制到 U 盘、压缩包直接跑

一、什么是 Python 便携版（Embedded Python）

核心定义

Python Embedded = 官方提供的“最小运行时 Python”

特点：

• ✅ 不依赖系统 Python

• ✅ 不写注册表

• ✅ 不污染系统

• ❌ 默认 锁死（不能 pip / 不能 site-packages）

📌 ComfyUI、Blender、很多商业软件都用这套

Embedded Python ≠ 普通 Python

二、下载 Python 便携版（正确版本）

1️⃣ 下载地址（官方）

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

选择：

Python 3.10.x → Windows → embeddable package (64-bit)

文件名类似：

python-3.10.13-embed-amd64.zip

💡 推荐 Python 3.10

• AI / PyTorch / Qt 生态最稳

• ComfyUI 也用 3.10

2️⃣ 解压后的“正常结构”（别慌）

python_embed/
├─ python.exe
├─ python310.dll
├─ python310.zip ← 标准库在这里
├─ python310._pth ← 最重要的控制文件
├─ vcruntime140.dll
└─ …

✅ 没有 Lib/ 是完全正常的 ✅ 标准库在 python310.zip

三、Embedded Python 的“解锁原理”（一定要理解）

默认状态（锁死）

Embedded Python 默认：

• ❌ 不加载 Lib

• ❌ 不加载 site-packages

• ❌ 不允许 pip

这是通过 python310._pth 控制的。

_pth 是什么？

它是：

Python 启动时的“白名单路径表”

• 只加载你写进去的路径

• 绝不偷偷读系统环境

📌 这就是它“便携 + 隔离”的核心

四、配置 Embedded Python（最关键部分）

✅ Step 1：手动创建目录（必须）

在 python_embed 目录下，新建：

python_embed/
├─ Lib/
│ └─ site-packages/

👉 Python 不会帮你建，你要自己建

✅ Step 2：编辑 python310._pth

打开：

python_embed\\python310._pth

把内容 完全改成下面这样（照抄）：

python310.zip
.
Lib
Lib\\site-packages

import site

每一行的意义

⚠️ 没有 import site = 一切白搭

五、给 Embedded Python 安装 pip（正确方式）

❌ 为什么 ensurepip 不存在？

Embedded Python 官方移除了：

• ensurepip

• venv

👉 所以你看到：

No module named ensurepip

是 正常现象

✅ 正确解法：get-pip.py（官方方案）

Step 1：下载 get-pip.py

地址：

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

放到：

python_embed\\get-pip.py

Step 2：用“便携 python.exe”运行

cd D:\\AudioTT\\python_embed
.\\python.exe get-pip.py

成功后会安装：

• pip

• setuptools

• wheel

到：

python_embed\\Lib\\site-packages\\

Step 3：验证 pip

.\\python.exe -m pip –version

输出示例：

pip 24.x from D:\\AudioTT\\python_embed\\Lib\\site-packages\\pip

✅ 说明成功

六、在便携 Python 中安装第三方库（正确姿势）

⚠️ 永远用你的 python.exe

.\\python.exe -m pip install faster-whisper

.\\python.exe -m pip install torch torchvision torchaudio –extra-index-url https://download.pytorch.org/whl/cu121

❌ 不要用：

pip install xxx

七、如何“确保不用系统 Python”（核心技巧）

方法一：始终用绝对路径

D:\\AudioTT\\python_embed\\python.exe app\\main.py

方法二：启动脚本（推荐）

run.bat（标准写法）

@echo off
set BASEDIR=%~dp0

set PYTHONHOME=%BASEDIR%python_embed
set PYTHONNOUSERSITE=1
set PATH=%BASEDIR%python_embed;%BASEDIR%python_embed\\Scripts;%PATH%

"%BASEDIR%python_embed\\python.exe" app\\main.py
pause

自检（一定要做）

在 main.py 里：

import sys
print(sys.executable)

必须输出：

D:\\AudioTT\\python_embed\\python.exe

八、为什么“没有 Lib 也能 import os/json？”

因为：

• 标准库在 python310.zip

• Python 会自动从 zip 里加载

📌 这是 Embedded Python 的设计亮点

九、推荐的“便携 AI 项目结构”（对标 ComfyUI）

AudioTT/
├─ python_embed/
│ ├─ python.exe
│ ├─ python310.zip
│ ├─ python310._pth
│ └─ Lib/
│ └─ site-packages/
│
├─ ffmpeg/
│ └─ ffmpeg.exe
│
├─ app/
│ ├─ main.py
│ ├─ gui.py
│ └─ asr_engine.py
│
├─ run.bat
└─ README.md

十、发布前“自检清单”（非常重要）

• sys.executable 指向便携 python

• 删除系统 Python，程序仍能跑

• pip 安装的库都在 Lib/site-packages

• _pth 中有 import site

十一句话终极总结（你要记住）

Python 便携版不是“装 Python”， 而是“控制 Python 只加载你允许的路径”。

你现在已经掌握了 ComfyUI 级别的环境构建能力。