如何解决 pip install -r requirements.txt UnicodeDecodeError: ‘utf-8’ codec can’t decode byte（编码/BOM）问题

Python系列Bug修复：PyCharm控制台pip install报错解决方案

如何解决 pip install -r requirements.txt UnicodeDecodeError: ‘utf-8’ codec can’t decode byte（编码/BOM）问题

摘要

在 Python 项目中，我们经常会遇到 pip install -r requirements.txt 命令报错，提示类似 UnicodeDecodeError: 'utf-8' codec can't decode byte 的问题。这个问题可能会让开发人员感到非常困惑，尤其是在 Windows、MacOS 或 Linux 环境中，Python 和 PyCharm 都是常见的开发工具。如果你也遇到了这个问题，本文将深入探讨其原因，并提供多种解决方案，帮助你快速定位和修复。

开发场景

在日常开发过程中，我们通常使用 pip 来安装 Python 项目的依赖，尤其是通过 requirements.txt 文件来批量安装所需包。然而，某些情况下，当执行 pip install -r requirements.txt 命令时，可能会遇到 UnicodeDecodeError 错误，提示 utf-8 codec can't decode byte。这种情况常见于字符编码或文件格式问题，可能是因为 requirements.txt 文件中包含了无法被 utf-8 解码的字符，或者是 BOM（字节顺序标记）问题。

开发环境

本篇文章适用于以下开发环境：

• 操作系统：macOS
• Python 版本：3.x
• 开发工具：PyCharm 2025

接下来，我们将逐一解析可能的原因，并提出解决方案。

一、可能原因及解决方案

1. module包没有安装，或者包名错误

问题描述：

如果你没有正确安装 requirements.txt 中列出的模块，或者模块名拼写错误，可能会导致 pip install 失败，并出现类似编码错误的提示。

解决方案：

检查 requirements.txt 文件中列出的所有包名，确认它们的正确性，并确保每个包都已正确安装。

2. 网络问题切换国内源解决

问题描述：

由于 Python 默认的 pip 镜像源位于国外，在国内访问时可能会遇到连接超时等问题，导致安装失败。

解决方案：

切换到国内的 pip 镜像源进行安装。常见的国内镜像源包括：

• 阿里云：https://mirrors.aliyun.com/pypi/simple/
• 清华大学：https://pypi.tuna.tsinghua.edu.cn/simple
• 豆瓣：https://pypi.douban.com/simple/

你可以通过以下命令临时切换镜像源：

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

或者在 pip.conf 或 pip.ini 配置文件中永久配置镜像源：

[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple

3. 忘了import

问题描述：

有时候，错误的出现可能是因为忘记在代码中导入需要的模块或包。

解决方案：

确保在使用某个包之前，已经正确地导入了它。例如：

import pandas as pd

4. 没有 __init__.py 文件

问题描述：

在 Python 中，如果你创建了一个包而没有 __init__.py 文件，Python 解释器可能无法识别该目录为一个包，从而导致导入错误。

解决方案：

检查你的包目录是否包含了 __init__.py 文件，如果没有，创建一个空的 __init__.py 文件即可。

5. package包的版本不对

问题描述：

有时，项目中要求的包版本与 requirements.txt 中指定的版本不一致，可能会导致安装错误，甚至出现 Unicode 编码问题。

解决方案：

检查 requirements.txt 中的包版本，并确保它们与你项目中实际需要的版本一致。可以使用如下命令更新包：

pip install --upgrade <package_name>

6. 自定义的包名与安装的包名相同

问题描述：

如果你自定义的包名与安装的第三方包的名称相同，可能会导致导入时冲突，从而引发错误。

解决方案：

避免自定义包名与已安装的第三方包重名。如果存在重名的情况，考虑修改自定义包的名称。

7. 没设置PYTHONPATH

问题描述：

PYTHONPATH 是 Python 用来查找模块的路径。如果你的自定义模块不在 PYTHONPATH 中，可能会导致导入错误。

解决方案：

通过设置 PYTHONPATH 环境变量来指定模块搜索路径：

export PYTHONPATH=$PYTHONPATH:/path/to/your/module

8. 自建的module包所在路径不在PYTHONPATH下

问题描述：

如果你将自己的模块放在了 PYTHONPATH 路径之外，Python 可能无法找到并导入该模块。

解决方案：

将模块所在路径加入 PYTHONPATH，或者将模块文件放入标准的 Python 模块路径下。

9. 不恰当的使用了相对导入

问题描述：

如果在包内使用相对导入时，路径错误或不清晰，可能会导致 ImportError 或其他错误。

解决方案：

使用绝对导入来避免路径问题。正确的导入方式如下：

from mypackage import mymodule

10. pip版本不是最新版

问题描述：

如果 pip 版本较旧，可能会出现无法识别某些依赖或安装错误的问题。

解决方案：

使用以下命令更新 pip：

python -m pip install --upgrade pip

二、编码和BOM问题解决方案

1. UTF-8编码问题

问题描述：

UnicodeDecodeError 错误通常是因为文件包含了非法的字符编码，特别是 BOM（字节顺序标记）问题。

解决方案：

确保 requirements.txt 文件采用 UTF-8 编码保存，并移除文件中的 BOM。可以使用编辑器（如 Sublime Text）重新保存文件，选择 UTF-8 编码，并确保不包含 BOM。你也可以使用如下命令查看文件的编码：

file -bi requirements.txt

2. 使用正确的文本编辑器保存文件

解决方案：

使用支持 UTF-8 编码的文本编辑器（如 VSCode 或 Sublime Text），并在保存时选择 UTF-8 编码格式。

三、总结

在使用 pip install -r requirements.txt 安装依赖时，遇到 UnicodeDecodeError 错误并不是罕见的现象。通过本文的多种解决方案，我们可以排查和修复编码问题、网络问题、版本问题等。希望这些解决方案能帮助你高效解决开发中的问题。如果你在开发过程中遇到其他问题，欢迎查看我的专栏获取更多 Bug 解决方案。

温馨提示🔔 更多 Bug 解决方案请查看 ==> 全栈 Bug 解决方案专栏

作者✍️名片