What is the meaning of "Failed building wheel for X" in pip install?

Question

This is a truly popular question here at SO, but none of the many answers I have looked at, clearly explain what this error really mean, and why it occurs.

One source of confusion, is that when (for example) you do pip install pycparser, you first get the error:

Failed building wheel for pycparser

which is then followed by the message that the package was:

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

What is going on here?

(I would like to understand how something can fail but still get installed and whether you can trust this package functioning correctly?)

So far the best partial explanation I have found is this.

Answer 1

(pip maintainer here!)

If the package is not a wheel, pip tries to build a wheel for it (via setup.py bdist_wheel). If that fails for any reason, you get the "Failed building wheel for pycparser" message and pip falls back to installing directly (via setup.py install).

Once we have a wheel, pip can install the wheel by unpacking it correctly. pip tries to install packages via wheels as often as it can. This is because of various advantages of using wheels (like faster installs, cache-able, not executing code again etc).

---

Your error message here is due to the wheel package being missing, which contains the logic required to build the wheels in setup.py bdist_wheel. (pip install wheel can fix that.)

---

The above is the legacy behavior that is currently the default; we'll switch to PEP 517 by default, sometime in the future, moving us to a standards-based process for this. We also have isolated builds for that so, you'd have wheel installed in those environments by default. :)

• PEP 517: A build-system independent format for source trees
• A blog post on "PEP 517 and 518 in Plain English"