How to Fix Python “setup.py bdist_wheel did not Run Successfully” Error

error: setup.py bdist_wheel did not run successfully. Exit code: 1

This frustrating message gives no hints about the root cause. Wheel files enable faster Python package installs, so when bdist_wheel fails, it prevents installing libraries needed for your projects.

In this comprehensive guide, we will demystify common causes and solutions for the **"setup.py bdist_wheel did not run successfully" error step-by-step.

What Does “setup.py bdist_wheel did not Run Successfully” Mean?

The setup.py script builds distributions of Python packages to share with others. The bdist_wheel command specifically creates wheel archives containing installable Python code.

Wheels are the preferred distribution format because they allow faster installs without needing to recompile code.

So when setup.py bdist_wheel fails during pip install, it blocks installing the library. This prevents using that Python package in your environment.

When Does This Error Occur?

The “did not run successfully exit code 1” error typically occurs when:

• Installing native Python packages with C extensions or binaries
• Using an incompatible Python version for the package
• On unsupported OS platforms like incompatible Python version and architecture combinations
• Due to missing dependencies needed during wheel creation
• With Python virtual environments using conflicting dependency versions

So while cryptic, this error usually indicates compatibility issues between the package, Python interpreter, platform, or dependencies.

Let’s explore the most common specific causes and solutions.

5 Common Causes and Fixes

Here are 5 frequent reasons for the bdist_wheel error along with corresponding troubleshooting fixes:

1. Incompatible Python Version

Some Python packages only support specific Python versions depending on conventions used:

setuptools dependency >= 46 requires Python >= 3.6
NumPy requires Python >= 3.7

If the Python version is too old for a package, bdist_wheel fails.

The Fix:

• Update to a supported Python version
• Try creating a dedicated virtual environment with updated Python version
• Install an older version of the package supporting current Python

For example, to install numpy supporting Python 3.5:

pip install numpy==1.16.0

2. Missing Compile Tools

Native Python packages with C extensions run compile commands during setup.py commands. If compilers like gcc and make are missing, native builds fail.

You may see compile errors like:

error: command 'x86_64-linux-gnu-gcc' failed with exit code 1

Or directly:

unable to execute 'gcc': No such file or directory

The Fix:

• Install build toolchain suite like build-essential on Linux
• macOS – install XCode command line tools
• Windows – install compilers like Visual Studio Build Tools or MinGW

To install compile tools on Debian/Ubuntu:

sudo apt update
sudo apt install build-essential

3. Incompatible Python Architecture

Python interpreters come in different “architectures” – 32 bit vs 64 bit, ARM vs x64, big-endian vs little-endian.

If the Python version differs from OS or hardware architecture, precompiled binaries in native packages won’t match – causing bdist_wheels to fail.

Example mismatch error:

File "/wheels/cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", line 1: ELF 64-bit LSB executable, x86-64 
error: [Errno 0] Error:

The Fix:

• Install Python version matching hardware architecture
• Compile package from source code overriding platform checks
• Use multi-architecture Docker images that contain compatible interpreters

For example, force architecture ignoring bdist_wheel checks:

python setup.py bdist_wheel -d build --plat-name macosx-11-x86_64

4. Contradictory Dependency Versions

If your environment contains conflicting versions of the same dependency, native packages may compile against incompatible libraries.

For example, if NumPy requires LibFFT v1.0 but SciPy forces LibFFT v0.9, bdist_wheel crashes.

Example conflicting dependency error:

error: Command "/venv/bin/python -u -c "import setuptools, 
tokenize;__file__='/tmp/pip-install-ey2x3o0i/numpy/setup.py';f=getattr
(tokenize, 'open', open)
(__file__);code=f.read().replace('\r\n', '\n');f.close();exec(compile
(code, __file__, 'exec'))" install --record /tmp/pip-record-jhcc5hld/
install-record.txt
--single-version-externally-managed --prefix /tmp/pip-build-env-54k1l9jz/
overlay --compile --install-headers /tmp/pip-build-env-54k1l9jz/overlay/include/site/python3.8/numpy"
 failed with error code 1 in /tmp/pip-install-ey2x3o0i/numpy/

The Fix:

• Standardize on dependency versions across libraries
• Install package first before other libraries to lock dependency
• Use virtual environments with fixed dependency versions

For example, ensure NumPy’s dependencies satisfy before SciPy:

mkvirtualenv scipy-env
pip install numpy
pip install scipy

5. Unsupported Platform

Packages with native code precompiled during bdist_wheel may not support the current operating system.

If the host platform does not match the wheel, you will see errors like:

networkx-2.6.3-cp39-cp39-win_amd64.whl is not a supported wheel on this platform.

The Fix:

• Try a generic OS wheel like manylinux
• Build wheel from source code for current platform
• Use Docker container matching wheel platform

Build wheel for current platform instead of downloaded binary wheel:

pip wheel networkx --no-binary :all: --wheel-dir=./wheelhouse/

Advanced Troubleshooting Tips

For tricky cases, try these advanced troubleshooting tips to further diagnose setup.py bdist_wheel failures:

• Specify verbose output to see full build logs:python setup.py bdist_wheel -v
• Test against fresh virtual environment to isolate dependency issues
• Upgrade setuptools & wheel in case of plugin conflicts:pip install setuptools wheel --upgrade
• Try compiling from source code without cached binaries:python setup.py bdist_wheel --no-use-wheel
• Watch for warning messages before errors during builds
• Check package README for known issues on given OS/Python version

Debugging setup scripts can be complicated – but methodically trying these fixes should bypass the did not run successfully error during wheel creation.

Troubleshooting Example: Installing Pandas

Let’s walk through a real troubleshooting example installing Pandas data analysis library.

When trying to pip install pandas, we get the dreaded bdist error:

Collecting pandas
  Using cached pandas-1.1.5.tar.gz (5.2 MB)
    ERROR: Command errored out with exit status 1:
     command: 'c:\users\max\envs\analysis\python.exe' -c 'import sys, setuptools, tokenize; sys.argv[0] = '"'"'C:\\Users\\max\\AppData\\Local\\Temp\\pip-install-p2crki5a\\pandas\\setup.py'"'"'; __file__='"'"'C:\\Users\\max\\AppData\\Local\\Temp\\pip-install-p2crki5a\\pandas\\setup.py'"'"';f=getattr(tokenize, '"'"'open'"'"', open)(__file__);code=f.read().replace('"'"'\r\n'"'"', '"'"'\n'"'"');f.close();exec(compile(code, __file__, '"'"'exec'"'"'))' egg_info --egg-base 'C:\Users\max\AppData\Local\Temp\pip-pip-egg-info-_4falkuc'
         cwd: C:\Users\max\AppData\Local\Temp\pip-install-p2crki5a\pandas\
    Complete output (23 lines):
    
    WARNING: The wheel package is not available.
         ERROR: setup.py: command 'C:\\Users\\max\\envs\\analysis\\python.exe' failed with exit code 1
    ...............................................................
    ERROR: setup.py: Command errored out with exit status 1:
     command: 'c:\users\max\envs\analysis\python.exe' -u -c 'import sys, setuptools, tokenize; sys.argv[0] = '"'"'C:\\Users\\max\\AppData\\Local\\Temp\\pip-wheel-cvs2otk6\\pandas\\setup.py'"'"'; __file__='"'"'C:\\Users\\max\\AppData\\Local\\Temp\\pip-wheel-cvs2otk6\\pandas\\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 'C:\Users\max\AppData\Local\Temp\pip-wheel-5l2ijkdx'
         cwd: C:\Users\max\AppData\Local\Temp\pip-wheel-cvs2otk6\pandas\
    Complete output (31 lines):
    usage: setup.py [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...]
       or: setup.py --help [cmd1 cmd2 ...]
       or: setup.py --help-commands
       or: setup.py cmd --help
    
    error: invalid command 'bdist_wheel'
    
    ----------------------------------------
    ERROR: Failed building wheel for pandas
    Running setup.py clean for pandas
    ERROR: Command errored out with exit status 1:
     command: 'c:\users\max\envs\analysis\python.exe' -u -c 'import sys, setuptools, tokenize; sys.argv[0] = '"'"'C:\\Users\\max\\AppData\\Local\\Temp\\pip-install-p2crki5a\\pandas\\setup.py'"'"'; __file__='"'"'C:\\Users\\max\\AppData\\Local\\Temp\\pip-install-p2crki5a\\pandas\\setup.py'"'"';f=getattr(tokenize, '"'"'open'"'"', open)(__file__);code=f.read().replace('"'"'\r\n'"'"', '"'"'\n'"'"');f.close();exec(compile(code, __file__, '"'"'exec'"'"'))' clean --all
         cwd: C:\Users\max\AppData\Local\Temp\pip-install-p2crki5a\pandas
    Complete output (6 lines):
    usage: setup.py [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...]
       or: setup.py --help [cmd1 cmd2 ...]
       or: setup.py --help-commands
       or: setup.py cmd --help
    
    error: invalid command 'clean'
    ----------------------------------------
ERROR: Command errored out with exit status 1: 'c:\users\max\envs\analysis\python.exe' -u -c 'import sys, setuptools, tokenize; sys.argv[0] = '"'"'C:\\Users\\max\\AppData\\Local\\Temp\\pip-install-p2crki5a\\pandas\\setup.py'"'"'; __file__='"'"'C:\\Users\\max\\AppData\\Local\\Temp\\pip-install-p2crki5a\\pandas\\setup.py'"'"';f=getattr(tokenize, '"'"'open'"'"', open)(__file__);code=f.read().replace('"'"'\r\n'"'"', '"'"'\n'"'"');f.close();exec(compile(code, __file__, '"'"'exec'"'"'))' install --record 'C:\Users\max\AppData\Local\Temp\pip-record-zi3ou27f\install-record.txt' --single-version-externally-managed --compile --install-headers 'c:\users\max\envs\analysis\include\site\python3.8\pandas' Check the logs for full command output.

The key warnings and errors indicate:

• Missing wheel package
• Invalid bdist_wheel command
• Unknown clean command

So the root cause is an outdated setuptools. Pandas requires wheel support along with newer setuptools APIs not available in the current environment.

We can confirm by checking setuptools version:

(analysis) C:\Users\max>python -c "import setuptools; print(setuptools.__version__)"
40.6.2

The fix is to upgrade setuptools and wheel packages before retrying pandas install:

pip install --upgrade setuptools wheel
Collecting setuptools
  Using cached setuptools-65.5.0-py3-none-any.whl (1.1 MB)
Installing collected packages: setuptools
  Attempting uninstall: setuptools
    Found existing installation: setuptools 40.6.2
Successfully uninstalled setuptools-40.6.2
Collecting wheel
  Using cached wheel-0.37.1-py2.py3-none-any.whl (35 kB)
Installing collected packages: wheel, setuptools
Successfully installed setuptools-65.5.0 wheel-0.37.1

Now pandas can compile its wheel distribution and installs successfully:

pip install pandas
Collecting pandas
  Using cached pandas-1.1.5.tar.gz (5.2 MB)
  Preparing metadata (setup.py) ... done
Building wheels for collected packages: pandas
  Building wheel for pandas (setup.py) ... done
  Created wheel for pandas: filename=pandas-1.1.5-cp38-none-win_amd64.whl size=10486185 sha256=ea02d1c15c43a6641ad23f3be5e5c5dfaf2296baef77ee28dad0fbfe76ec348f
  Stored in directory: c:\users\max\appdata\local\pip\cache\wheels\43\bc\0e\7c781d1d03ad318b3589ac81c92246802435a5932ee928b43e
Successfully built pandas
Installing collected packages: pandas
Successfully installed pandas-1.1.5

So the problem was fixed by upgrading outdated setuptools/wheel just before retrying install.

Hopefully walking through this real example gives a methodology to follow when encountering cryptic bdist_wheel errors!

Avoiding Bdist_wheel Errors With Virtual Environments

An effective way to avoid bdist_wheel errors altogether is using virtual environments for all Python projects.

Virtualenvs sandbox all dependencies into a self-contained Python environment isolated from system packages:

python -m venv venv
source venv/bin/activate

Versions lock inside the virtualenv to eliminate conflicts across projects and packages.

Upgrading modules like setuptools also avoids impacting system Python environment.

Isolate all NLP, data science, web apps or other Python project into virtualenvs for dependency consistency and reproducible builds.

Conclusion

Fixing the setup.py bdist_wheel did not run successfully error just takes a bit of detective work to determine the root cause.

Follow the troubleshooting tips outlined to identify and solve:

• Incompatible Python versions
• Missing compiler toolchains
• Architecture mismatches
• Contradictory dependencies
• Platform incompatibilities

Hopefully demystifying the meaning behind this message along with systematic fixes helps resolve package install failures.

Using virtual environments also sidesteps the issue by isolating dependencies. Remember to activate the virtualenv first before running pip install commands.

With a bit of sleuthing, you’ll be able to get native Python packages compiling wheels and installing properly. Let me know if any tricky bdist_wheel errors still persist after trying all recommended fixes!