pip install 中的 "Failed building wheel for X" 是什么意思？

Question

这是一个在SO上真正流行的问题，但我查看过的许多答案中，没有一个清楚地解释了这个错误实际上意味着什么，以及为什么会发生这种情况。

混淆的一个来源是，当你执行例如pip install pycparser时，首先会出现错误：Failed building wheel for pycparser，然后是包安装成功的消息：Successfully installed pycparser-2.19。

# pip3 install pycparser

Collecting pycparser
  Using cached https://files.pythonhosted.org/packages/68/9e/49196946aee219aead1290e00d1e7fdeab8567783e83e1b9ab5585e6206a/pycparser-2.19.tar.gz
Building wheels for collected packages: pycparser
  Running setup.py bdist_wheel for pycparser ... error
  Complete output from command /usr/bin/python3 -u -c "import setuptools, tokenize;__file__='/tmp/pip-install-g_v28hpp/pycparser/setup.py';f=getattr(tokenize, 'open', open)(__file__);code=f.read().replace('\r\n', '\n');f.close();exec(compile(code, __file__, 'exec'))" bdist_wheel -d /tmp/pip-wheel-__w_f6p0 --python-tag cp36:
  Traceback (most recent call last):
    File "<string>", line 1, in <module>
    ...
    File "/usr/lib/python3.6/site-packages/pkg_resources/__init__.py", line 2349, in resolve
      module = __import__(self.module_name, fromlist=['__name__'], level=0)
  ModuleNotFoundError: No module named 'wheel.bdist_wheel'

  ----------------------------------------
  Failed building wheel for pycparser
  Running setup.py clean for pycparser
Failed to build pycparser
Installing collected packages: pycparser
  Running setup.py install for pycparser ... done
Successfully installed pycparser-2.19

这里发生了什么？

（我希望理解一件事情如何可以失败但仍然被安装，以及你是否可以信任这个软件包的正确功能？）

到目前为止，我找到的最好的部分解释是这个。

- not2qubit

---

当pip找不到满足要求的wheel时，它会下载源代码压缩包并尝试在本地构建一个wheel。构建成功后，wheel将被存储在pip的缓存中以供未来重新安装使用。如果构建wheel失败，pip则切换到从源代码压缩包进行传统安装（调用python setup.py install）。 - hoefling

在您的情况下，您缺少“wheel”包，因此“pip”无法从源分发构建轮。如果您想明确禁用构建轮，请使用“--no-binary”标志：pip install somepkg --no-binary=somepkg。或者使用pip install somepkg --no-binary=:all:，但要注意，这将禁用所有选定的软件包（包括依赖项）的轮，如果某个软件包需要安装的没有源分布，则安装将失败。 - hoefling

@hoefling：你的第一个评论是真正的原因，可以作为答案。第二个评论是错误的：--no-binary将指示pip仅下载并使用源分发。防止它构建本地二进制轮子的旗帜确实是--no-cache-dir。 - Serge Ballesta

您可以在 https://pypi.org/project/pycparser/ 上查看 PyPI 网站，然后请求 文件。您可以看到只有一个 .tar.gz 文件，它是 PyPI 上的源分发包（wheel 文件将具有 .whl 扩展名）。 - Serge Ballesta

@SergeBallesta，然而，我没有预料到--no-cache-dir会隐式禁用wheel构建；这让我感到有些惊讶。我一直以为--no-cache-dir只是忽略本地缓存目录（读和写都是），所以可以使用它来重建本地wheel而不是使用缓存的wheel。今天学到了新东西！ - hoefling

Answer 1

（pip维护者在此！）

更新：从Python 3.12开始，不再需要这个步骤，因为pip将自动在新的虚拟环境中使用隔离构建。

快速复制粘贴：

pip install wheel

在使用venv创建的每个新的虚拟环境中都要这样做。

继续阅读以了解详细信息和解释。

---

如果包不是一个wheel，pip会尝试为其构建一个wheel（通过setup.py bdist_wheel）。如果由于任何原因（例如缺少系统级库、与您的系统不兼容、构建的wheel中的版本字符串错误等）导致构建失败，您将收到“Failed building wheel for {...}”的消息。

在某些情况下，pip目前会回退到通过setup.py install进行安装，因此安装仍然可能成功。尽管如此，pip总是尽可能通过wheel安装软件包。这是因为使用wheel有各种优势（如更快的安装速度、可缓存、不再执行代码等），而且它是一种标准化的格式；不同于（已弃用的）setup.py install接口。

---

你在这里遇到的错误信息是由于缺少wheel包，该包包含了在setup.py bdist_wheel中构建轮子所需的逻辑。（pip install wheel可以解决这个问题，但它无法解决由于系统配置导致的构建时间问题）

---

在将来的某个时候，我们将默认切换到更现代的构建系统（如果您是软件包作者，您可以通过添加一个pyproject.toml文件来选择加入），这将通过隔离的构建环境来解决这个问题，您将在其中安装wheel。:)

• PEP 517: 源代码树的构建系统独立格式
• 一篇关于“PEP 517和518的简明解释”的博文

- pradyunsg

---

在编写 OP 时，我已经安装了 wheel 包。另外请添加 PEP517 的链接。 - not2qubit

你之前安装过setuptools或wheel的旧版本吗？如果没有，那似乎是失败的原因。无论如何，从pip的角度来看，它未能构建wheel，因此正常安装。 - pradyunsg

还要确保在您操作的虚拟环境中安装了wheel包（而不仅仅是机器）。 - PiperWarrior

没有任何现在还没有被弃用的。 - pradyunsg

我们已经进入2022年了，但这仍然是一个问题。pip install wheel做了一些“事情”，但在尝试完成与创建Python虚拟环境相关的原始安装时，它们仍然失败。我不得不坚持使用基于Windows的设置。真是浪费时间啊。 - AndyUK

Answer 2

昨天，我运行pip3 install hddfancontrol时遇到了相同的错误：Failed building wheel for hddfancontrol。结果显示Failed to build hddfancontrol，原因是error: invalid command 'bdist_wheel'以及Running setup.py bdist_wheel for hddfancontrol ... error。通过运行以下命令来修复错误：

 pip3 install wheel

(来源于这里。)

另外，“wheel”可以直接从这里下载。下载后，可以通过运行以下命令进行安装：

pip3 install "/the/file_path/to/wheel-0.32.3-py2.py3-none-any.whl"

- Matthew Wai

---

pip3 install wheel 很好用，甚至在 'python3 -m venv' 中也可以使用。今天我是新手。 - Manohar Reddy Poreddy

即使我安装了轮子，它仍然无法工作！ - vatsalay

这实际上解决了当python --version抛出错误，但python3 --version可以工作的情况。谢谢！ - Ale Ponzo

将 wheel 包添加到您的 setup_requires 选项中，将为您解决问题，[options] setup_requires = wheel >= 0.37.1 setuptools >= 44.0.0 - farch

Answer 3

由于除了我自己没人提及这一点，因此我对上述问题的解决方案通常是确保使用pip install <package> --no-cache-dir来禁用缓存副本。

- not2qubit

---

如果你的目标只是删除该信息，那么这可能算作一种修复，否则我会称其为一种解决方法。 - Nils Magnus

因为 PyPI 上的带宽不是“免费”的，而缓存构建好的 wheel 文件可以让后续安装变得更快。 - pradyunsg

为什么那个回答被接受为问题的答案？它并没有回答这个问题。 - PascalIv

因为他自己提出了这个问题并回答了它。我认为这样他能够接受自己的答案。听起来很奇怪，但也有可能是这样。 - Amit Amola

@PascalIv 因为那个错误曾经在其他不同的情况下出现过。后来我找到了一个对我有效的答案，并自然地接受了它。正如你所看到的，有许多不同的解决方案适用于其他人，但对我并不适用。也许这不是一个百分之百可靠的接受答案的方法，但这就是我们必须要面对的灵活性... - not2qubit

Answer 4

在我的情况下，在创建虚拟环境后更新pip版本，这将把pip从9.0.1更新为20.3.1。

python3 -m venv env/python
source env/python/bin/activate
pip3 install pip --upgrade

但是，信息是...

Using legacy 'setup.py install' for django-avatar, since package 'wheel' is not installed.

然后，在更新pip之后，我安装了wheel包。

python3 -m venv env/python
source env/python/bin/activate
pip3 install --upgrade pip
pip3 install wheel

而且信息是...

Building wheel for django-avatar (setup.py): started
default:   Building wheel for django-avatar (setup.py): finished with status 'done'

- Jantones

Answer 5

从软件包部署的角度来看，解决这个问题可能会有所帮助。

有很多教程介绍如何将软件包发布到PyPi。以下是我使用过的一些教程; medium real python 我的经验是，大多数这些教程只让你使用源文件的.tar，而不是wheel文件。因此，当安装使用这些教程创建的软件包时，我收到了“无法构建wheel”的错误。

后来我在PyPi上找到了Python软件基金会文档的链接PSF Docs。我发现他们的设置和构建过程略有不同，并确实包括构建一个wheel文件。

在使用官方记录的方法后，我安装软件包时不再收到错误信息。

因此，错误可能只是开发人员打包和部署项目的方式问题。我们中没有人天生知道如何使用PyPi，如果他们偶然看到了错误的教程 - 嗯，你可以自己想象。

我相信这不是错误的唯一原因，但我愿意打赌这是主要原因之一。

- SteveJ

Answer 6

当你没有wheel所需的必要软件包时，通常会出现此错误。如果使用的是Python3，则安装python3-dev，如果是使用Python2，则安装python2-dev。

sudo apt-get install python3-dev 

或者

sudo apt-get install python2-dev

- demerit

---

迟早我们会执行这个命令，所以最好先执行它。这是正确的答案，因为可能需要多个依赖项，而这将处理必要的内容。 - Isaac Philip

这个答案救了我，我一直在尝试在WSL上安装PandasGUI，但是一直出现错误“无法为evdev构建轮子”，而且互联网上的所有答案都没有用，但是你的答案有效！ - Gabriel Caldas

Answer 7

错误：

系统：AWS EC2实例（t2小型）

问题：在安装OpenCV Python时，执行命令：

pip3 install opencv-python

  Problem with the CMake installation, aborting build. CMake executable is cmake
  
  ----------------------------------------
  Failed building wheel for opencv-python
  Running setup.py clean for opencv-python

我的解决方法

pip3 install --upgrade pip setuptools wheel

执行完这个命令之后，你可能仍然会收到以下错误信息：

    from .cv2 import *
ImportError: libGL.so.1: cannot open shared object file: No such file or directory

安装libgl解决了我的错误。

sudo apt update
sudo apt install libgl1-mesa-glx

希望这能帮到你。

- Hemant c

---

pip3 install --upgrade pip setuptools wheel 对我也解决了问题。 - wotter

Answer 8

尝试这个：

sudo apt-get install libpcap-dev libpq-dev

在我安装这两个时有效。

有关更多信息，请参见链接此处。

- t w

Answer 9

在Ubuntu 18.04上，我遇到了这个问题，因为wheel的apt包不包含wheel命令。我认为pip尝试导入wheel python包，如果成功，则假定wheel命令也可用。但是Ubuntu打破了这个假设。 apt中的python3代码包名为python3-wheel。这是自动安装的，因为python3-pip推荐它。

apt中的python3 wheel命令包名为python-wheel-common。同时安装它可以解决“构建wheel失败”的错误。

- JanKanis

---

错误报告 - JanKanis

Answer 10

在安装一个需要 'isal' 的软件包时，我遇到了这个问题，我花了几个小时都无法解决 isal 安装失败的问题：

  ----------------------------------------
  ERROR: Failed building wheel for isal
Failed to build isal
ERROR: Could not build wheels for isal which use PEP 517 and cannot be installed directly

我的解决方案是安装libtool。

yum install libtool

- J.K