跨平台（Mac / Windows）Python 项目依赖包提取教程（基于 pigar）

本教程适配 Mac / Linux / Windows 系统，以「项目代码可正常运行」为前提，
通过 micromamba 管理 Python 环境，并使用 pigar 基于项目 import 分析生成依赖清单，
最终得到一个 干净、可迁移、可复现 的 requirements-pigar.txt 文件。

适用场景：科研项目、工程项目、团队协作、跨电脑/跨系统环境迁移

声明：本教程由豆包和ChatGPT协助完成

---

一、前置准备

1. 环境要求（说明）

• Python ≥ 3.8（推荐 3.10）
• 已安装 micromamba（跨平台环境管理工具，conda 的轻量替代）
• 待分析的 Python 项目（可正常运行，依赖已装全）

⚠️ 重要说明
pigar 不是 pip freeze，它以代码 import 分析为主，再结合本地环境/索引解析到对应 PyPI 包名与版本。
动态导入、插件机制、运行时 import 仍可能需要人工补充。

---

二、安装 micromamba

Mac / Linux（代码块）

# 官方安装脚本
curl micro.mamba.pm/install.sh | bash

# 使环境变量生效（zsh 用户）
source ~/.zshrc

Windows（PowerShell，代码块）

# 下载可执行文件
Invoke-WebRequest -Uri https://github.com/mamba-org/micromamba-releases/releases/latest/download/micromamba-win-64.exe -OutFile micromamba.exe

# 临时加入 PATH（永久需手动配置系统环境变量）
$env:PATH += ";$PWD"

Windows 必做：初始化 PowerShell（否则 activate 可能无效）

# 设置 micromamba 根目录（建议固定）
$env:MAMBA_ROOT_PREFIX = "$HOME\micromamba"

# 初始化 PowerShell
.\micromamba.exe shell init -s powershell -p $env:MAMBA_ROOT_PREFIX

⚠️ 执行完成后 关闭当前 PowerShell，重新打开，再继续后续步骤。

---

三、步骤 1：创建并激活环境

创建环境（代码块）

micromamba create -n py-dep-env python=3.10 -y

激活环境（代码块）

micromamba activate py-dep-env

终端前缀出现 (py-dep-env) 即表示成功。

---

四、步骤 2：配置 pip 阿里云镜像（永久生效）

Mac / Linux（代码块）

mkdir -p ~/.config/pip

cat << EOF > ~/.config/pip/pip.conf
[global]
index-url = https://mirrors.aliyun.com/pypi/simple/
[install]
trusted-host = mirrors.aliyun.com
EOF

macOS 说明：
若存在 ~/Library/Application Support/pip/pip.conf，pip 也可能读取该路径。

Windows（PowerShell，代码块）

mkdir $env:APPDATA\pip -Force

@"
[global]
index-url = https://mirrors.aliyun.com/pypi/simple/
[install]
trusted-host = mirrors.aliyun.com
"@ | Out-File -FilePath $env:APPDATA\pip\pip.ini -Encoding utf8

验证 pip 配置（代码块）

pip config -v list

---

五、步骤 3：安装并验证 pigar

安装 pigar（代码块）

pip install pigar

验证版本（代码块）

pigar --version

不同 pigar 版本参数略有差异，以 pigar -h 为准。

---

六、步骤 4：提取依赖清单

1. 进入项目根目录（说明）

cd /path/to/your/python/project        # Mac / Linux
# cd D:\my-python-project             # Windows

2. 生成原始依赖清单（两种稳定写法，任选其一）

写法 A：默认生成 requirements.txt

pigar generate

写法 B：指定输出文件（推荐）

pigar gen -f requirements-pigar-raw.txt .

---

七、步骤 5：清理注释，生成干净清单

Mac / Linux（代码块）

grep -v "^#" requirements-pigar-raw.txt | grep -v "^$" > requirements-pigar.txt

Windows（PowerShell，代码块）

Get-Content requirements-pigar-raw.txt |
Where-Object { $_ -notmatch "^#" -and $_ -notmatch "^$" } |
Set-Content requirements-pigar.txt -Encoding utf8

建议 保留 requirements-pigar-raw.txt 作为排错/溯源文件。

查看结果（代码块）

cat requirements-pigar.txt

示例（代码块）

requests==2.31.0
pandas==2.1.4
flask==2.3.3

---

八、步骤 6：版本兼容性优化（可选但推荐）

pigar 默认生成 精确版本（==），迁移或长期维护建议改为兼容区间：

requests>=2.28.0,<3.0
pandas>=2.0.0,<3.0
flask>=2.2.0,<3.0

---

九、步骤 7：在其他电脑安装依赖

安装依赖（代码块）

pip install -U -r requirements-pigar.txt

验证（代码块）

pip list
python main.py

建议同时说明 Python 版本要求（如 3.10），避免跨版本问题。

---

十、常见问题与避坑

1. pigar 参数报错
   不同版本支持的参数不同，先执行：

   pigar -h
   

2. 依赖缺失

   • 动态 import / 插件机制需手动补充
   • 检查 PyPI 实际包名（如 beautifulsoup4 而非 bs4）

3. Windows activate 失败

   • 通常是未执行 micromamba shell init
   • 不是单纯的管理员权限问题

4. 应急方案（兜底）

   pip freeze > requirements-freeze.txt
   

---

十一、流程总结

• micromamba：跨平台、可复现的 Python 环境
• pigar：基于项目 import 的精准依赖提取
• 清理注释：生成可迁移 requirements
• 兼容版本区间：降低环境复现风险

最终产出：

• requirements-pigar.txt（安装用）
• requirements-pigar-raw.txt（排错/参考用）