오류: 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 인터프리터에 pip을 연결하려면 python -m pip install wheel로 설치하세요. 빌드에 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 패키지를 사용할 수 있어야 합니다. 없다면 python -m pip install setuptools로 해당 환경에 설치하세요.

인터프리터와 설치된 패키지를 확인한 다음에만 빌드 도구 업데이트를 고려하세요. 명령은 python -m pip install --upgrade pip setuptools wheel입니다. 업데이트는 오래되었거나 일관성이 없는 환경에 도움이 될 수 있지만, 잘못된 Python으로 명령을 실행하는 문제를 해결하지는 않습니다. setup_requires=['wheel'] 설정은 활성 빌드 환경을 바로잡는 방법이 아닙니다. Windows C++ 빌드 도구는 패키지에 네이티브 컴파일이 필요한 경우에 관련이 있으며, 이것만으로 누락된 bdist_wheel 명령이 제공되지는 않습니다.