ImportError: Setuptools라는 모듈이 없습니다.

Python은 코드를 실행하는 인터프리터가 setuptools 패키지를 찾지 못할 때 ImportError: No module named setuptools 오류를 보고합니다. Python 3에서는 보통 ModuleNotFoundError: No module named 'setuptools' 형태로 나타납니다. setuptools는 오랫동안 사용되어 온 Python 패키지 빌드 및 배포 라이브러리이며, 많은 도구와 setup.py 기반 설치가 여전히 이에 의존합니다. 해결 방법은 거의 항상 설치하는 것이지만, 코드를 실행하는 것과 동일한 환경에 설치해야 하며 — 대부분의 시도가 바로 여기서 잘못됩니다. 이 가이드는 해당 환경을 식별하고, pip 또는 conda를 통해 setuptools를 설치한 뒤, 수정이 제대로 되었는지 확인하는 방법을 보여줍니다.

오류를 이해하고 활성 Python 환경 식별

이 오류는 주로 두 가지 상황에서 발생합니다:

• setuptools가 해당 환경에 아예 설치되지 않은 경우. Python 3.12 이상에서 생성된 새 venv 환경과 여러 Linux 배포판의 Python은 더 이상 이를 번들로 포함하지 않습니다.
• setuptools가 설치되어 있지만 다른 인터프리터용인 경우. 한 컴퓨터에는 시스템 Python, 하나 이상의 venv 환경, conda 베이스 등 여러 Python 설치가 공존할 수 있으며, 하나에 설치해도 다른 것에는 도움이 되지 않습니다.

따라서 첫 번째 진단 질문은 “setuptools가 설치되어 있는가?“가 아니라 “어떤 인터프리터가 실패하는 코드를 실행하며, 그 인터프리터가 setuptools를 볼 수 있는가?“입니다. 인터프리터 경로는 명령 하나로 확인할 수 있습니다: python -c "import sys; print(sys.executable)". sys.executable은 추측하지 않습니다. 셸이 먼저 해석하는 항목만 보여주는 which python이나 where python과는 다릅니다. 출력된 경로가 venv 디렉터리 안에 있으면(예: .venv/bin/python), 코드는 해당 가상 환경에서 실행되는 것입니다.

다음으로 중요한 것은 동일한 인터프리터가 보는 설치된 패키지 목록이므로, 실제로 어떤 패키지를 볼 수 있는지 확인합니다. 다음 예제를 실행해 보세요:

이 섹션의 코드와 표시되는 레이블 또는 출력은 영어로 유지됩니다.

import importlib.util

for name in ("pip", "setuptools"):
    found = importlib.util.find_spec(name) is not None
    print(name, "->", "found" if found else "missing")

pip -> found
setuptools -> missing

find_spec은 패키지를 실제로 임포트하지 않고 임포트 시스템이 해당 패키지를 찾을 수 있는지 보고합니다. 실패하는 코드를 실행하는 것과 동일한 인터프리터로 스크립트를 실행하세요. 여기서 pip -> found는 해당 인터프리터에 동작하는 설치 도구가 있음을 의미하고, setuptools -> missing은 패키지가 그 인터프리터에 보이지 않음을 확인해 줍니다 — 다음 섹션의 설치가 정확히 이 문제를 해결합니다. 실행 결과가 setuptools -> found인데도 프로그램이 계속 실패한다면, 다른 인터프리터가 프로그램을 시작하는 것입니다 — IDE, 작업 실행기 또는 cron 작업이 터미널과 별도로 구성된 경우에 흔히 발생합니다. 이 경우는 마지막 섹션에서 다룹니다.

조회 경계 자체를 직접 보는 것도 가치가 있습니다. 임포트 시스템이 이름을 해석할 수 없으면, 인터프리터는 찾지 못한 모듈의 이름을 담은 ModuleNotFoundError — ImportError의 서브클래스 — 를 발생시킵니다. 아무것도 제거하지 않고도 정확히 같은 실패 서명을 재현할 수 있습니다: 아래 예제는 setuptools를 숨기는 임포트 파인더를 삽입해 인터프리터를 설치가 누락된 것과 동일한 상태로 만들고, 실패한 임포트가 보고하는 내용을 캡처합니다.

import importlib.abc
import sys

class HideSetuptools(importlib.abc.MetaPathFinder):
    def find_spec(self, name, path=None, target=None):
        if name == "setuptools":
            raise ModuleNotFoundError("No module named 'setuptools'")
        return None

sys.meta_path.insert(0, HideSetuptools())

try:
    import setuptools
except ModuleNotFoundError as exc:
    print(type(exc).__name__ + ":", exc)
    print("setuptools is not visible to this interpreter")

ModuleNotFoundError: No module named 'setuptools'
setuptools is not visible to this interpreter

실패하는 프로그램 아래의 트레이스백이 setuptools를 지목하는 동일한 ModuleNotFoundError 줄로 끝난다면, 위의 진단이 적용되며 다음 섹션의 설치가 이를 해결합니다. 트레이스백 안의 다른 오류 — 예를 들어 setuptools 자체의 누락된 종속성이나 실패한 setup.py 빌드 단계 — 는 다른 원인을 가리키므로, 아무것도 설치하기 전에 마지막 예외 줄을 비교하세요.

코드를 실행하는 환경에 setuptools 설치

신뢰할 수 있는 설치 명령은 -m 플래그를 통해 pip를 특정 인터프리터에 바인딩하므로, 패키지가 정확히 그 인터프리터가 검색하는 위치에 놓입니다: python -m pip install setuptools.

python을 이전 단계에서 보고된 인터프리터로 바꾸세요: python3, Windows 런처를 통한 py -3, 또는 .venv/bin/python -m pip install setuptools와 같은 전체 경로를 사용할 수 있습니다. 활성화된 venv 안에서는 일반 python이 이미 해당 환경을 가리키므로, venv로 관리되는 프로젝트에서는 활성화 후 python -m pip가 가장 간단한 방법입니다. “혹시 몰라서” setuptools를 전역으로 설치하지 마세요 — 실패하는 코드를 실행하는 인터프리터에 설치하고, 프로젝트 작업에는 시스템 Python보다 가상 환경을 우선하세요.

환경이 conda로 관리되는 경우, 패키지를 자체 메타데이터에 기록할 수 있도록 대신 conda 자체 설치 도구를 사용하세요: 대상 환경을 활성화하고 conda install setuptools를 실행하거나, conda install -n myenv setuptools로 직접 대상을 지정합니다. conda 경로는 conda로 관리되는 환경에만 적용됩니다. 그 외의 모든 경우에는 위의 python -m pip 명령이 일반적인 해결책입니다.

내부적으로 pip는 Python Package Index(PyPI)에서 패키지를 다운로드하여 환경의 site-packages 디렉터리 아래에 설치합니다 — 정확히 임포트 시스템이 검색하는 위치입니다. 따라서 머신이 PyPI 또는 구성된 패키지 미러에 접근할 수 있어야 합니다. 설치가 반복적으로 시간 초과되거나 pypi.org를 해석하지 못하면, 재시도하기 전에 네트워크, 프록시 또는 pip 인덱스 구성을 확인하세요.

설치 확인 및 지속적인 오류 문제 해결

설치에 사용한 것과 동일한 인터프리터 바인딩으로 확인합니다: python -m pip show setuptools. 성공하면 패키지 메타데이터 — Name, Version, Summary 및 Location 줄 — 를 출력합니다. Location은 앞서 sys.executable이 보고한 것과 동일한 환경 프리픽스 아래에 있어야 합니다 — 그렇지 않다면 코드를 실행하는 환경이 아닌 다른 환경에 설치한 것입니다. pip가 WARNING: Package(s) not found: setuptools를 출력하면, 패키지가 그 인터프리터용으로 아예 설치되지 않은 것이므로 올바른 -m pip 바인딩으로 돌아가 설치하세요.

마지막 확인은 동일한 인터프리터로 python -c "import setuptools"를 실행하는 것입니다. 아무것도 출력하지 않고 프롬프트로 돌아와야 합니다. 다시 ImportError를 발생시키면 인터프리터가 여전히 패키지를 볼 수 없는 것입니다.

오류가 지속되면 다음 원인을 순서대로 확인하세요:

• 인터프리터 불일치. 코드가 터미널에서 사용하는 것과 다른 인터프리터로 실행됩니다. 스크립트의 실행기(IDE 인터프리터 설정, shebang 줄, cron 항목)를 위의 sys.executable 출력과 비교한 다음, 런처를 해당 인터프리터로 지정하거나 해당 인터프리터의 -m pip를 통해 설치를 다시 실행하세요.
• 오래된 pip. 오래된 pip는 최신 패키지를 아예 가져오거나 설치하지 못할 수 있습니다. 설치 자체가 제대로 동작하지 않을 때, 동일한 인터프리터에 바인딩하여 python -m pip install --upgrade pip로 업그레이드한 다음 setuptools 설치를 재시도하세요. 이것은 손상되었거나 오래된 설치 도구를 위한 조건부 단계이지, ImportError의 일반적인 원인이 아닙니다.
• 손상된 환경. 활성화 스크립트나 site-packages가 손상된 경우, 복구하는 것보다 새 venv를 만드는 것이 더 빠릅니다. python -m venv .venv로 생성하고, macOS와 Linux에서는 source .venv/bin/activate, Windows에서는 .venv\Scripts\activate로 활성화한 다음, setuptools와 프로젝트 종속성을 다시 설치하고 그곳에서 코드를 다시 실행하세요.
• 빌드 시점 임포트. pip가 다른 것을 소스에서 설치하는 동안 오류가 나타나면, 실패한 임포트는 --no-build-isolation으로 실행되는 setup.py 빌드 또는 setup.py를 직접 호출한 것에서 비롯될 수 있습니다. 빌드를 수행하는 인터프리터용으로 setuptools를 설치하세요.

pip show가 올바른 프리픽스 아래에서 패키지를 보고하고 동일한 인터프리터로 import setuptools가 성공하면 ImportError는 해결된 것입니다. 단독 pip가 아닌 python -m pip처럼 설치를 인터프리터에 바인딩하는 방식을 유지하면 이러한 종류의 오류가 다시 발생하는 것을 방지할 수 있습니다.