Python pip 설치 시 "No module named 'setuptools.command.test'" 에러 원인과 해결 방법
Problem
파이썬 프로젝트를 진행하면서 RandomWords와 같은 특정 패키지를 pip install로 설치할 때 설치가 실패하는 경우가 있습니다. 특히 패키지의 메타데이터를 준비하는 setup.py egg_info 단계에서 에러가 발생하며 프로세스가 중단됩니다. 이때 터미널에 ModuleNotFoundError: No module named 'setuptools.command.test'라는 에러 메시지가 출력됩니다. 이는 pip 자체의 문제가 아니라, 설치하려는 패키지의 내부 설치 스크립트(setup.py)에서 발생하는 문제입니다.
Background
파이썬 패키지들은 과거부터 패키징과 배포를 위해 setuptools 라이브러리의 setup.py 방식을 널리 사용해 왔습니다. 일부 패키지들은 테스트 커맨드를 처리하기 위해 setup.py 내에서 from setuptools.command.test import test와 같이 특정 모듈을 불러옵니다. 하지만 파이썬 생태계가 발전함에 따라 setuptools의 유지보수 팀은 2024년 7월 배포된 72.0.0 버전부터 더 이상 사용되지 않는(deprecated) command.test 모듈을 완전히 제거했습니다. 따라서 최신 버전의 setuptools가 설치된 파이썬 환경에서 이 모듈을 참조하는 오래된 패키지를 설치하려고 하면, 해당 모듈을 찾을 수 없어 에러가 발생하는 것입니다.
Solution
이 문제를 해결하는 가장 확실한 방법은 에러를 유발하는 setuptools의 버전을 문제가 없는 이전 버전으로 낮추는 것입니다.
1. pip를 사용하여 setuptools 다운그레이드 (가장 간단한 방법)
현재 가상환경이나 시스템에 설치된 setuptools의 버전을 72.0.0 미만으로 강제 지정하여 설치합니다.
# setuptools 버전을 72.0.0 미만으로 다운그레이드 및 설치합니다.
# 이미 설치되어 있다면 -U (또는 --upgrade) 옵션을 통해 덮어씁니다.
python -m pip install -U 'setuptools<72.0.0'
# setuptools 다운그레이드가 완료된 후, 원래 설치하려던 패키지를 설치합니다.
python -m pip install RandomWords
이 방법은 빠르고 직관적이며, 대부분의 로컬 개발 환경이나 CI/CD 파이프라인에서 즉각적으로 문제를 해결할 수 있습니다.
2. 의존성 관리 도구(Poetry)를 사용한 버전 고정
Poetry나 Hatch와 같은 모던 파이썬 패키지 관리자를 사용 중이라면, 프로젝트 설정 파일에서 setuptools의 버전을 명시적으로 제한하는 것이 좋습니다.
# pyproject.toml 파일 내 의존성 섹션
[tool.poetry.dependencies]
python = "^3.12"
# setuptools 버전을 72.0.0 미만으로 고정하여 호환성 문제를 방지합니다.
setuptools = "<72.0.0"
RandomWords = "*"
설정 후 아래 명령어를 통해 의존성을 업데이트합니다.
# 변경된 pyproject.toml을 바탕으로 의존성을 다시 설치합니다.
poetry update
이 방식은 다른 팀원들이 프로젝트를 클론하여 세팅할 때도 동일한 에러를 겪지 않도록 보장해 주는 장점이 있습니다.
Deep Dive
사실 setuptools 72.0.0 버전은 배포 직후 수많은 패키지에서 이와 같은 호환성 에러가 발생하자, PyPI에서 일시적으로 배포가 철회(Yanked)되었고 모듈 제거가 2024년 11월 15일로 연기된 바 있습니다. 하지만 이는 임시방편일 뿐이므로, 근본적으로는 문제가 되는 패키지의 메인테이너가 코드를 수정해야 합니다. 파이썬 생태계는 현재 setup.py를 직접 실행하는 방식에서 벗어나, pyproject.toml을 표준으로 사용하는 PEP 517/518 기반의 모던 패키징 시스템으로 전환하고 있습니다. 개발자라면 의존하는 패키지가 최신 빌드 시스템을 지원하는지 확인하고, 수년간 업데이트가 없는 패키지(RandomWords 등)는 유지보수가 활발한 최신 대안 패키지로 교체하는 것을 적극적으로 고려해야 합니다.
Conclusion
setuptools.command.test 모듈 에러는 파이썬 패키징 도구의 발전 과정에서 발생하는 과도기적인 호환성 문제입니다. 당장 패키지 설치가 필요하다면 setuptools<72.0.0으로 버전을 낮추어 문제를 빠르게 해결할 수 있습니다. 하지만 프로덕션 환경의 장기적인 안정성을 위해서는 유지보수가 활발히 이루어지고 최신 파이썬 표준(pyproject.toml)을 따르는 패키지를 선택하는 것이 바람직합니다.