Skip to main content

How to Solve "error: invalid command 'bdist_wheel'" in Python

The error "error: invalid command 'bdist_wheel'" in Python usually indicates that the wheel package is not installed in your current Python environment. The bdist_wheel command is used by setuptools to build "wheel" packages (.whl files), which are a standard built-package format for Python.

This guide explains how to fix this error by installing or upgrading wheel and setuptools, and provides troubleshooting steps.

Understanding the Error​

The bdist_wheel command is part of the setuptools package and is used to build wheel files. Wheel files (.whl) are a built-package format for Python that can speed up installation, especially for packages with C extensions.

If wheel isn't installed, setuptools can't create them, and you'll see this error. This most commonly happens when you're trying to build a Python package from source (e.g., using python setup.py bdist_wheel or pip install . on a source distribution).

Solution: Installing or Upgrading wheel and setuptools​

The primary solution is to install or upgrade the wheel package. It's also a very good idea to upgrade setuptools at the same time, as outdated versions of setuptools can cause problems.

Run the following commands in your terminal/command prompt:

pip install --upgrade pip setuptools wheel
  • pip install --upgrade pip setuptools wheel: This command does the following:
    • pip install: Uses pip to install packages.
    • --upgrade: Upgrades pip, setuptools and wheel to the latest versions. This is very important, as outdated versions of these packages are a frequent source of build problems.
    • pip, setuptools and wheel: Specifies the packages to install/upgrade.

If you have multiple python versions, you might have to specify which version of python you want to use by using python -m pip:

python -m pip install --upgrade pip setuptools wheel  # Or python3 -m pip

Always use virtual environments for your Python projects. This isolates project dependencies and prevents conflicts. It also makes it much easier to manage package versions.

  1. Create a virtual environment (if you don't have one):

    python3 -m venv venv  # Or python -m venv venv, or py -m venv venv

  2. Activate the environment:

    • Linux/macOS: source venv/bin/activate
    • Windows (cmd.exe): venv\Scripts\activate.bat
    • Windows (PowerShell): venv\Scripts\Activate.ps1
      • If you get the error: "...ps1 can not be loaded because running scripts is disabled on this system", try this solution: 
        Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

  3. Install/upgrade wheel and setuptools inside the activated environment:

    pip install --upgrade pip setuptools wheel

Your terminal prompt should change (e.g., (venv) $).

Troubleshooting​

If you still get the error after installing wheel, consider these possibilities:

Incorrect Python/pip Version​

Make sure you're using the correct pip (or pip3, python -m pip) for the Python version you intend to use. If you have multiple Python versions installed, it's easy to accidentally install wheel into the wrong one. Using virtual environments greatly simplifies this.

Outdated setuptools​

Even if you think setuptools is up-to-date, try upgrading it explicitly:

pip install --upgrade setuptools

Corrupted Installation​

Sometimes, a package installation can become corrupted. Try uninstalling and reinstalling wheel:

pip uninstall wheel
pip install wheel
  • You should also uninstall and reinstall the package that is causing the error.

setup.py Issues​

If you're building a package from source and encountering this error within a setup.py file, ensure that:

  • You import the correct modules. 
    import setuptools
    from setuptools import setup
    # Other imports
  • You add wheel to setup_requires 
    setup(
        #...
        setup_requires=['wheel']
    )

Conclusion​

The error: invalid command 'bdist_wheel' error almost always indicates a missing or outdated wheel package.

  • Installing or upgrading wheel (and setuptools) using pip install --upgrade pip setuptools wheel, preferably within a virtual environment, will resolve the issue.
  • If you're building a package from source, double-check your setup.py file.

By following these steps, you can ensure that your Python environment is correctly configured for building wheel packages.

Table of Contents