本文分享了Python开发者在使用pip安装软件包时常遇到的两个棘手问题及其解决方案。第一个是ModuleNotFoundError: No module named 'docopt'，根源在于包自身安装脚本在导入前未安装所需模块，解决方法是手动将docopt.py文件放入项目根目录。第二个是UnicodeDecodeError: 'gbk' codec can't decode，常见于中文Windows系统，原因是安装脚本读取UTF-8编码的文件时，Windows默认的GBK编码无法解析。解决方法是设置环境变量PYTHONUTF8=1，强制Python使用UTF-8编码进行文件读写。这两个问题都源于包的setup.py脚本设计不完善，但通过仔细分析错误日志，均可有效解决。

📦 **ModuleNotFoundError: No module named 'docopt' 的解决方法** 当pip安装过程中遇到此错误，意味着安装脚本（setup.py）在尝试导入名为'docopt'的模块时失败，因为该模块尚未安装。这通常是包自身打包方式的问题，安装脚本在执行前需要先读取docopt模块信息（如版本号），但此时docopt并未安装。解决此问题的直接方法是手动获取docopt.py源文件（可从其官方代码仓库下载），并将其放置在项目根目录下。随后重新运行pip install命令，安装脚本就能在当前路径找到docopt.py，从而顺利完成安装。

💻 **UnicodeDecodeError: 'gbk' codec can't decode 的解决方法** 此编码错误在中文Windows系统上尤为常见，当安装脚本尝试读取项目说明文件（如README.md）时发生，原因是Windows默认使用GBK编码，而许多开源项目的说明文件通常使用UTF-8编码。当安装脚本试图用GBK编码解析UTF-8文件时，会因无法识别的字符而报错。解决此问题的有效方法是临时设置环境变量PYTHONUTF8=1。该设置会强制Python在当前操作中优先使用UTF-8编码进行文件读写，从而避免了编码不匹配导致的错误。

🔧 **问题根源与启示** 文中提到的两个pip安装问题，其共同点在于错误根源都出在包的setup.py安装脚本设计不够完善，未能充分考虑跨平台兼容性或依赖的正确安装顺序。通过仔细阅读错误日志，开发者可以定位问题的具体环节。解决这些问题需要对Python的包管理机制和文件编码有一定的了解，并能够灵活运用命令行工具进行辅助操作，从而有效解决安装过程中的“拦路虎”。

使用Python的开发者，对 pip 命令可以说是又爱又恨。我们依赖它来管理项目包，但安装过程也常常伴随着各种报错。

版本冲突、缺少C++编译环境、网络问题……这些都是老熟人了。遇到多了，解决起来也算得心应手。但有时候，pip 会抛出一些不那么常见的错误，根源不在我们的环境，而在于包本身。

最近我在安装英伟达的开源项目 Parakeet 时，就遇到了两个这样的“小插曲”。记录下来，希望能帮助遇到类似问题的朋友。

第一个坎：ModuleNotFoundError: No module named 'docopt'

安装进行到一半，终端弹出了这个错误。

Preparing metadata (setup.py) ... errorerror: subprocess-exited-with-error× python setup.py egg_info did not run successfully....ModuleNotFoundError: No module named 'docopt'...

这个错误有点奇怪。我正是在尝试安装一个包，它却告诉我找不到它自己。这就像一个需要钥匙才能打开的盒子，而钥匙就在盒子里面。

问题出在 docopt 这个包的安装脚本 setup.py 上。脚本在执行安装前，试图先导入 docopt 模块，可能是为了读取版本号。但此时，docopt 还没有被安装到环境中，Python自然找不到它，于是安装失败。

这是一个由包自身打包方式引起的问题，而不是 pip 的错。

解决方法很直接：既然它找不到，我们就手动把文件放到它面前。

从网上找到 docopt.py 这个源文件。它通常在docopt的官方代码仓库里。https://raw.githubusercontent.com/docopt/docopt/master/docopt.py将这个 docopt.py 文件下载下来，直接放到你的项目根目录下。然后，回到终端，重新运行之前的 pip install 命令。

这一次，当安装脚本需要导入 docopt 时，它能在当前路径下找到这个文件，于是顺利地继续执行，问题解决。

第二个坎：UnicodeDecodeError: 'gbk' codec can't decode...

解决了上一个问题后，安装继续进行。没过多久，又一个新的错误出现了。

Preparing metadata (setup.py) ... errorerror: subprocess-exited-with-error× python setup.py egg_info did not run successfully....UnicodeDecodeError: 'gbk' codec can't decode byte 0xae in position 268: illegal multibyte sequence...

这是一个编码错误，在中文Windows系统上尤其常见。

错误日志告诉我们，问题出在另一个依赖包 indic_numtowords 的 setup.py 文件上。脚本在尝试读取一个文件（通常是README.md这样的项目说明文件）时出了错。

原因在于，Windows系统默认使用GBK编码。而很多开源包的说明文件都是用更通用的UTF-8编码保存的。当安装脚本试图用GBK的方式去读取一个UTF-8文件时，遇到了不认识的字符，就报错了。

这个问题同样是包的开发者没有考虑到跨平台编码的兼容性。

最简单且无副作用的解决方法是，临时告诉Python，在当前这次操作中，请统一使用UTF-8编码。

打开你的命令行工具（CMD或PowerShell）。

在执行安装命令之前，先输入一条指令来设置环境变量。这个设置只在当前窗口生效，关掉就没了。

如果你用的是CMD，输入：

set PYTHONUTF8=1

如果你用的是PowerShell，输入：

$env:PYTHONUTF8=1

然后，就在这个窗口里，重新运行你的pip install命令。

设置之后，Python在读写文件时会优先使用UTF-8，编码不匹配的问题也就迎刃而解。

这两个问题都不算复杂，但初次遇到可能会有些不知所措。它们的共同点是，错误根源都在于包本身的 setup.py 安装脚本写得不够完善。通过仔细阅读错误日志，我们就能找到线索，对症下药。希望这段经历能给你带来一点启发。