为什么 Dify 安装 Python 包总踩坑？
作为 Star 超 10 万 + 的开源 LLM 开发平台，Dify 的插件化机制让功能扩展更灵活，但很多开发者在安装 Python 依赖时频频碰壁：
明明装了包却提示 “ModuleNotFoundError”？
安装插件时遭遇 “版本冲突” 回滚报错？
内网环境下依赖下载超时、镜像配置无效？
沙箱运行时提示 “缺少系统库”？
其实问题核心就 3 类：环境未隔离、依赖版本不兼容、网络 / 配置不当。这篇教程从基础安装到离线部署，手把手教你搞定所有场景！
1. 先搭 “干净” 的 Python 环境（关键！）
Dify 推荐 Python 3.12 + 版本，优先用虚拟环境隔离，避免污染全局环境：
# 1. 创建虚拟环境（Windows/Mac通用）python -m venv dify_env# 2. 激活环境# Windows：dify_env\Scripts\activate# Mac/Linux：source dify_env/bin/activate# 3. 升级pip（避免旧版本解析依赖出错）pip install --upgrade pip setuptools
2. 两种安装方式，按需选择
方式 1：直接安装单个依赖包
适合需要新增独立 Python 库（如 pymysql、requests）：
# 示例：安装pymysqlpip install pymysql
安装后验证：在 Dify 插件代码中添加import pymysql，无报错即成功。
方式 2：通过 requirements.txt 批量安装
适合插件依赖多个包的场景，先创建配置文件：
# requirements.txt（示例：LangChain+OpenAI SDK）langchain==0.1.0 # 锁定版本，避免冲突openai==1.30.1pydantic<2.0.0 # 兼容约束
执行安装命令：
pip install -r requirements.txt3. 沙箱环境特殊配置（Docker 部署场景）
如果 Dify 用 Docker 部署，需将依赖添加到沙箱目录：
1.进入沙箱依赖目录：
cd dify/docker/volumes/sandbox/dependencies
2.新建 / 修改 requirements.txt，添加所需包
3.重启 Dify 沙箱容器，自动触发安装：
docker-compose restart sandbox
注意：部分系统依赖包（如 mysqlclient）可能安装失败，建议替换为纯 Python 实现的替代库（如用 pymysql 替代 mysqlclient）。
避坑篇：解决 90% 的安装失败问题
问题 1：依赖版本冲突（最常见！）
典型报错：ImportError: cannot import name 'xxx' from 'langchain'
原因：插件要求的包版本与环境已安装版本不兼容（如插件需 LangChain 0.1.0，环境已装 0.2.0）。
解决方案：
1.用pipdeptree分析依赖树：
pip install pipdeptreepipdeptree | grep langchain # 查看冲突依赖
2.严格锁定版本：在 requirements.txt 中指定精确版本（如langchain==0.1.0），而非宽松约束（langchain>=0.1.0）
3.优先使用 Dify 官方推荐的依赖组合，避免自行推测兼容性。
问题 2：国内网络下载超时
解决方案：配置国内镜像源，加速依赖下载：
pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
Dify 1.x + 版本已支持自定义 Pip 镜像，可在配置文件中设置：
# .env文件PIP_MIRROR_URL=https://mirrors.aliyun.com/pypi/simple/
问题 3：内网 / 离线环境安装
场景：无外网权限，无法下载依赖包。
解决方案：离线打包依赖，本地安装：
1.在外网环境下载依赖包到本地目录：
pip download -r requirements.txt -d ./packages # 下载到packages文件夹
2.拷贝 packages 目录和 requirements.txt 到内网服务器，执行离线安装：
pip install --no-index --find-links=./packages -r requirements.txt
3.进阶方案：使用开源脚本打包 Dify 插件及依赖（支持市场 / GitHub / 本地插件），一键生成离线包：
脚本地址：dify-plugin-repackaging
问题 4：签名验证失败
报错：Plugin signature verification failed
原因：插件来源非官方，或传输过程中文件损坏。
解决方案：
优先从 Dify 官方市场下载插件（marketplace.dify.ai）
验证插件文件完整性，重新下载损坏的.difypkg 包
1.用 Poetry 替代 pip：更智能的依赖解析，自动生成锁文件，避免 “在我这能跑” 问题：
# 安装Poetrycurl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -# 安装依赖poetry install # 自动读取pyproject.toml
2.定期检查依赖：用pip check命令检测缺失或冲突的依赖：
pip check # 输出冲突信息，针对性修复
3.版本兼容原则：优先选择与 Dify 核心依赖兼容的包版本，尤其注意：
LangChain：避免跨大版本升级
pydantic：Dify 部分组件暂不支持 v2.x
OpenAI SDK：建议使用 1.x 版本
Dify 安装 Python 包的核心是 “环境隔离 + 版本锁定 + 网络优化”：
新手：用 venv + 镜像源，按步骤安装基础依赖；
企业用户：用离线打包 + 虚拟环境，解决内网部署和版本冲突；
避坑关键：锁定版本、优先官方依赖、替换系统级依赖包。
按照这套方法，90% 的安装问题都能一次性解决！如果遇到特殊报错，欢迎在评论区留言，一起交流解决方案～
