지난 글에서 잠깐 언급했던, Gemini 원격 코딩 어시스턴트를 만들면서 겪은 설치 문제를 이번 글에서 자세히 다룹니다. 최신 환경이 오히려 발목을 잡는, 은근히 자주 마주치는 종류의 문제였습니다.

증상: 기본적인 패키지 설치가 안 된다

aider를 설치하려고 하니 의존 패키지 중 하나가 설치 단계에서 실패했습니다. 에러 메시지를 따라가 보니 distutils.msvccompiler를 찾을 수 없다는 식의, 파이썬 빌드 도구 체인과 관련된 에러였습니다. numpy처럼 오래되고 널리 쓰이는 과학계산 라이브러리조차 순순히 설치되지 않았습니다.

원인: 너무 최신 파이썬

이 환경의 기본 파이썬 버전은 3.14였습니다. 최신 버전을 쓰는 것 자체는 보통 좋은 일이지만, 이번엔 오히려 문제가 됐습니다. distutils는 오래전부터 파이썬 표준 라이브러리에서 단계적으로 제거되어 온 모듈이고, 여러 과학계산·빌드 관련 패키지들이 이 모듈에 의존한 채로 아직 최신 파이썬 버전에 맞춰 업데이트되지 않은 상태였습니다. 결과적으로 “너무 최신이라서” 오래된 패키지들과 호환이 깨지는, 흔치 않지만 실제로 마주치면 당황스러운 상황이었습니다.

문제 해결 흐름

해결: 공식 설치 스크립트로 우회

직접 pip install로 하나하나 문제를 해결하는 대신, aider가 공식적으로 제공하는 설치 스크립트(aider-install)를 사용했습니다. 이 스크립트는 내부적으로 uv(빠른 파이썬 패키지/환경 관리 도구)를 이용해서, 시스템 기본 파이썬과 완전히 격리된 별도의 파이썬 환경을 알아서 구성하고 그 안에 필요한 패키지들을 설치합니다. 시스템의 3.14 환경을 직접 건드리지 않고, 호환되는 버전의 파이썬을 별도로 마련해서 그 안에서만 동작하게 하는 방식이라 충돌 자체가 발생하지 않았습니다.

돌아보며

이 문제는 “패키지를 하나씩 고쳐서 최신 파이썬에 맞추는” 방향으로 접근했다면 훨씬 오래 걸렸을 겁니다. 대신 “애초에 문제가 되는 환경 자체를 격리시킨다"는 방향으로 우회하니 훨씬 빠르게 해결됐습니다. 이 시리즈 앞부분에서 다룬 apt-get 설치 문제(GitHub Releases에서 바이너리를 직접 받아 우회)와도 비슷한 패턴입니다 — 표준적인 방법이 막혔을 때는, 그 표준 경로를 억지로 뚫으려 하기보다 문제가 되는 부분을 격리하거나 우회하는 쪽이 더 실용적인 경우가 많다는 걸 다시 확인했습니다.

핵심 요약

🤖 이 포스팅은 AI의 도움을 받아 작성되었습니다.