エラー: Python の無効なコマンド Bdist_wheel

error: invalid command 'bdist_wheel' というメッセージは通常、setup.py を実行しているPython環境で、ビルドプロセスがwheelコマンドを見つけられないことを示します。まず、その環境にwheelをインストールしてください。pipのアップグレードは後から試すトラブルシューティングであり、必ず解決するわけではありません。

bdist_wheelが使えない原因を調べる

bdist_wheelは、wheelパッケージが提供するsetuptoolsのビルドコマンドです。よくある原因は、ビルドに使うインタープリターにwheelが入っていないこと、または別のインタープリターに紐づいたpipでインストールしたことです。シェルでどのPythonとpipが選ばれるかを確認し、インストールと従来形式のビルドコマンドの両方で同じインタープリターを使ってください。たとえば、python -m pip --versionを実行すると、pythonに紐づくpipを確認できます。プロジェクトの実行にpython3を使っている場合は、両方のコマンドでpython3を使います。

python setup.py bdist_wheelは従来形式のパッケージング手順です。現在もこの方法を使うプロジェクトでは、次のセクションで直接的な対処法を説明します。新しいパッケージング手順を使うプロジェクトでは、このコマンドが使えると決めつけず、プロジェクトで指定されているビルド手順に従ってください。

実行中のPython環境にwheelをインストールする

python -m pip install wheelを使うと、選択したpythonインタープリターに紐づいたpipでインストールできます。ビルドにpython3を使う場合は、python3 -m pip install wheelを実行してください。有効化済みの仮想環境では、その環境のpythonを同じように使います。その後、python setup.py bdist_wheel（または対応するpython3コマンド）を再実行します。どのインタープリターを対象にしているか分からない場合は、単独のpipコマンドを避けてください。

次の短いプログラムは、実行中のPythonインタープリターに対応するコマンドの組み合わせを表示します。これはコマンドの選び方を示す例で、パッケージのインストールやディストリビューションのビルドは行いません。

import sys

python = sys.executable
print(f"{python} -m pip install wheel")
print(f"{python} setup.py bdist_wheel")

それでもビルドでbdist_wheelが使えないと表示される場合は、インストールコマンドとビルドコマンドが同じインタープリターを使っていること、また両方を実行するシェルで仮想環境が有効になっていることを確認してください。python -m pip show wheelを使うと、どの環境にパッケージがあるかを確認できます。表示された環境が、ビルドに使う予定の環境と一致しているか確認してください。

setup.pyを確認し、ビルドツールを更新する

環境を確認してもエラーが続く場合は、setup.pyを調べてください。古いdistutils.coreのインポートを使っているプロジェクトでは、setup.pyでfrom setuptools import setupとしてsetupをインポートし、setup(name="example-package", version="1.0")のようにプロジェクトのメタデータを渡すことで、setuptoolsに切り替えられます。これは設定方法を示す例であり、プロジェクト全体のビルド手順ではありません。setuptoolsパッケージも同じ環境に必要です。入っていない場合は、その環境でpython -m pip install setuptoolsを実行してください。

インタープリターとインストール済みパッケージを確認した後でのみ、ビルドツールの更新を検討してください。更新にはpython -m pip install --upgrade pip setuptools wheelを使えます。古い環境や整合性の取れていない環境では役立つことがありますが、誤ったPythonでコマンドを実行している問題は解決しません。setup_requires=['wheel']の設定は、実際にビルドで使う環境を修正する代わりにはなりません。WindowsのC++ビルドツールが関係するのは、パッケージのネイティブコンパイルが必要な場合です。それだけで不足しているbdist_wheelコマンドが使えるようになるわけではありません。