Kiwoom CLI 설치 중 키링 오류, 왜 이렇게 자주 발생할까
Kiwoom CLI를 우분투나 WSL 환경에 설치하다 보면 거의 예외 없이 마주치는 벽이 있습니다. 바로 “사용 가능한 운영체제 자격 증명 저장소를 찾을 수 없습니다”라는 keyring 오류입니다. GUI가 없는 서버 환경에서는 이 문제가 한 번으로 끝나지 않고, 해결할 때마다 새로운 형태의 오류가 연쇄적으로 나타나는 경우가 많습니다.
이 글에서는 실제로 개발 서버 환경에서 Kiwoom CLI를 설치하며 겪은 다섯 단계의 오류와 각 단계의 해결 과정을 순서대로 정리했습니다. 같은 오류 메시지로 검색해서 들어오신 분이라면, 본인이 지금 어느 단계에 있는지 확인하고 해당 섹션만 바로 참고하셔도 됩니다.
1단계: 자격 증명 저장소를 찾을 수 없다는 오류
설치 마지막 단계인 “저장 및 마무리” 과정에서 “사용 가능한 운영체제 자격 증명 저장소를 찾을 수 없습니다”라는 메시지가 뜨는 것이 가장 먼저 만나는 문제입니다. 이는 파이썬의 keyring 라이브러리가 계정 정보를 안전하게 저장할 OS 기본 자격 증명 저장소를 찾지 못해서 발생합니다.
데스크톱 GUI가 없는 WSL, 리눅스 서버, 도커 컨테이너 환경에서 특히 자주 나타나는 증상입니다. 해결책은 크게 세 가지로, 파이썬 대체 키링 패키지를 설치하거나, OS 레벨의 키링 패키지를 직접 설치하거나, 아예 환경 변수로 계정 정보를 우회 등록하는 방법입니다. 이 중 대부분의 경우 첫 번째 방법인 파이썬 대체 키링 설치가 가장 간단하고 확실합니다.
2단계: gnome-keyring 설치 후에도 이어지는 팝업 오류
OS 자격 증명 패키지(dbus-x11, gnome-keyring)를 설치한 뒤 재시도하면 “Failed to create the collection: Prompt dismissed” 라는 새로운 오류가 나타날 수 있습니다. 이 오류의 원인은 gnome-keyring이 암호 저장소를 처음 생성할 때 비밀번호 입력용 GUI 팝업 창을 띄우려다, 화면이 없는 CLI 환경이라 실패하기 때문입니다.
즉 GUI 기반 키링 자체가 서버 환경과 근본적으로 맞지 않는 구조라는 뜻입니다. 이 문제를 우회하려면 팝업이 필요 없는 파일 기반 키링 방식으로 강제 전환해야 합니다. 구체적으로는 keyrings.alt 패키지를 설치한 뒤 PYTHON_KEYRING_BACKEND 환경 변수를 keyrings.alt.file.PlaintextKeyring으로 지정하면, GUI 팝업 없이 로컬 파일에 인증 정보가 저장됩니다.
3단계: externally-managed-environment 오류와 PEP 668
pip install keyrings.alt를 그대로 실행하면 최신 우분투(23.04 이상)에서는 “externally-managed-environment” 오류로 막히는 경우가 많습니다. 이는 시스템 전역 파이썬 환경이 꼬이는 것을 막기 위해 도입된 PEP 668 정책 때문입니다. 전역 pip 설치를 원천 차단해 시스템 안정성을 지키려는 의도입니다.
이를 우회하는 방법은 상황에 따라 세 가지로 나뉩니다. 독립된 개발 서버라면 --break-system-packages 옵션을 붙여 강제 설치하는 것이 가장 빠르고, 시스템 안정성을 우선한다면 apt install python3-keyrings.alt처럼 우분투 공식 패키지로 설치하는 편이 안전합니다. 장기적으로 가장 권장되는 방식은 프로젝트 폴더 안에 python3 -m venv venv로 가상 환경을 만들고 그 안에서 설치하는 것으로, 파이썬 생태계의 표준 관행이기도 합니다.
4단계: No module named ‘keyrings’ — 격리된 실행 환경의 함정
시스템에 keyrings.alt를 정상 설치했는데도 Kiwoom CLI 실행 시 ModuleNotFoundError: No module named 'keyrings' 오류가 다시 발생하는 경우가 있습니다. 이 단계에서 많은 사람들이 놓치는 지점이 있는데, 바로 Kiwoom CLI가 uv라는 패키지 관리자를 통해 시스템과 완전히 분리된 전용 가상 환경 안에서 실행되고 있다는 사실입니다.
시스템 파이썬에 아무리 패키지를 깔아도, uv tool로 설치된 프로그램은 자신만의 독립된 환경만 바라보기 때문에 해당 패키지를 인식하지 못합니다. 해결하려면 시스템이 아니라 Kiwoom CLI 전용 가상 환경 안에 직접 keyrings.alt를 주입해야 합니다. 전용 환경의 실행 파일 경로(홈 디렉토리 하위의 uv tools 경로)를 지정해 pip install keyrings.alt를 실행하면 되는데, 다만 이 경로는 환경마다 다르므로 본인 시스템에서 uv tool dir이나 관련 설정으로 정확한 위치를 먼저 확인하는 것이 안전합니다.
5단계: uv 도구 환경에는 pip 자체가 없는 경우
전용 환경 경로로 pip를 실행하려 했더니 애초에 pip 실행 파일 자체가 존재하지 않는 경우도 있습니다. uv로 생성된 도구(tool) 전용 환경에는 pip가 기본 포함되지 않는데, uv 자체가 패키지 관리 역할을 대신하기 때문입니다.
이때는 uv pip install keyrings.alt --python <전용 환경의 python 경로> 형태로, uv 명령어를 통해 해당 가상 환경의 파이썬에 직접 패키지를 설치해야 합니다. 만약 처음부터 uv tool install로 Kiwoom CLI를 설치하는 단계라면, --with keyrings.alt 옵션을 함께 지정해 처음부터 필요한 패키지를 묶어 설치하는 방법도 있습니다. 이렇게 하면 이후 단계에서 별도로 패키지를 주입할 필요 없이 한 번에 문제를 예방할 수 있습니다.
전체 해결 흐름 요약
정리하면 keyring 오류 해결은 다음 순서로 접근하는 것이 효율적입니다.
- 1단계:
keyrings.alt패키지로 파일 기반 키링 확보 - 2단계: GUI 팝업이 필요 없도록
PYTHON_KEYRING_BACKEND환경 변수 지정 - 3단계: PEP 668 정책 우회 (가급적 가상 환경 사용 권장)
- 4단계: 실행 프로그램이 격리된 환경(uv tool 등)에 있는지 먼저 확인
- 5단계: 격리 환경에 맞는 도구(
uv pip등)로 패키지 주입
자주 묻는 질문 (FAQ)
Q. --break-system-packages 옵션을 써도 안전한가요?
A. 독립된 개발/테스트 서버라면 크게 문제되지 않지만, 여러 프로젝트가 공존하는 운영 서버라면 시스템 파이썬 환경을 오염시킬 수 있어 가상 환경 사용을 권장합니다.
Q. PYTHON_KEYRING_BACKEND 환경 변수는 왜 자꾸 사라지나요?
A. 터미널 세션에서 export로 설정한 환경 변수는 해당 세션에만 유효합니다. 재부팅이나 새 터미널을 열 때마다 다시 설정하고 싶지 않다면 ~/.bashrc 등 쉘 설정 파일 맨 아래에 추가해두면 됩니다.
Q. uv tool 환경인지 아닌지는 어떻게 확인하나요?
A. 오류 로그의 트레이스백 경로에 uv/tools라는 문자열이 포함되어 있다면 uv로 격리 설치된 환경입니다. 이 경우 시스템 전역이 아니라 해당 도구 전용 환경에 패키지를 설치해야 합니다.
마치며
Kiwoom CLI의 keyring 오류는 하나의 원인이 아니라, GUI 부재·PEP 668 정책·uv 격리 환경이라는 서로 다른 세 가지 요인이 겹치면서 단계적으로 나타나는 문제입니다. 오류 메시지만 보고 성급하게 해결책을 적용하기보다는, 지금 자신이 어느 단계의 문제를 겪고 있는지 먼저 파악하는 것이 시행착오를 줄이는 지름길입니다. 이 글의 순서대로 하나씩 짚어가면 대부분의 환경에서 무리 없이 설치를 마칠 수 있을 것입니다.