ppt-master库下执行 pip install requirements.txt 报 UnicodeDecodeError: gbk 解码失败问题记录

pip install requirements.txt 报 UnicodeDecodeError: gbk 解码失败问题记录问题现象在 Windows 环境下执行项目依赖安装命令pip install-r requirements.txt或python-m pip install-r requirements.txt出现如下错误UnicodeDecodeError: gbk codec cant decode byte 0xae in position 212: illegal multibyte sequence decoding with cp936 codec failed错误发生在pip读取requirements.txt阶段还没有真正开始安装依赖。问题原因Windows 中文系统下Python / pip 在某些情况下会使用系统默认编码GBK或CP936读取文本文件。但项目中的requirements.txt实际是UTF-8编码文件里包含中文注释或特殊字符例如# PPT Master Dependencies / PPT Master 依赖如果pip按GBK/CP936去读取 UTF-8 文件就可能触发UnicodeDecodeError: gbk codec cant decode byte ...本质原因是文件编码是 UTF-8但 pip 按 GBK/CP936 解码解决方案一在 requirements.txt 顶部声明 UTF-8 编码在requirements.txt第一行添加# -*- coding: utf-8 -*-例如# -*- coding: utf-8 -*- # PPT Master Dependencies / PPT Master 依赖 python-pptx0.6.21 requests2.31.0如果项目中存在嵌套依赖文件例如顶层requirements.txt引用了另一个文件-r skills/ppt-master/requirements.txt那么被引用的文件也建议加上同样的编码声明# -*- coding: utf-8 -*-然后重新执行python-m pip install-r requirements.txt解决方案二临时强制 Python 使用 UTF-8在 PowerShell 中执行$env:PYTHONUTF81python-m pip install-r requirements.txt这个环境变量只对当前 PowerShell 会话生效。解决方案三使用纯 ASCII 的 requirements.txt如果不需要中文注释也可以把requirements.txt中的中文和特殊符号删掉只保留依赖项python-pptx0.6.21 requests2.31.0 beautifulsoup44.12.0这种方式最简单直接但会损失注释说明。推荐做法推荐使用第一种方式# -*- coding: utf-8 -*-原因是不需要删除中文注释对项目其他使用者更友好不依赖当前终端环境变量可以避免 Windows GBK 默认编码带来的读取问题。总结这个问题不是依赖包本身安装失败而是pip读取requirements.txt时的编码不匹配导致的。排查思路如下如果错误中出现UnicodeDecodeError并且包含gbk、cp936同时发生在读取requirements.txt阶段那么优先检查requirements.txt是否是 UTF-8 编码并在文件顶部添加# -*- coding: utf-8 -*-然后重新执行python-m pip install-r requirements.txt