[Python] SSL: CERTIFICATE_VERIFY_FAILED 에러 해결 가이드

최근 파이썬으로 시스템을 구축하거나 외부 API를 연동하는 프로젝트를 세팅하다 보면, 터미널을 붉게 물들이는 에러를 마주할 때가 있습니다. 바로 개발자들의 시간을 가장 많이 뺏는 SSL 인증서 오류입니다.

 

오늘은 검색창에 에러 메시지를 복사해서 이 글을 찾아오신 분들을 위해, 왜 이런 문제가 발생하는지 근본적인 원인을 파악하고, 보안을 해치지 않으면서 가장 우아하게 해결하는 방법을 정리해 드립니다.

 

SSL: CERTIFICATE_VERIFY_FAILED 에러 해결 가이드

 

🚨 문제 상황: 지긋지긋한 SSL 인증서 검증 실패

터미널에서 pip install을 실행하거나 파이썬 코드 내에서 requests로 외부 요청을 보낼 때 다음과 같은 에러가 발생합니다.

...<생략>...
(Caused by SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1010)')))

 

이 에러 로그의 의미는 명확합니다. **"서버가 보낸 SSL 인증서를 신뢰할 수 있는지 내 컴퓨터에서 검증하려고 했는데, 발급자(Issuer)의 인증서를 찾을 수 없다"**는 뜻입니다.

 

🔍 원인 분석: 파이썬은 왜 내 컴퓨터의 인증서를 모를까?

일반적으로 웹 브라우저는 윈도우나 macOS 운영체제(OS) 자체에 내장된 '루트 인증서 저장소(Trust Store)'를 참조합니다. 하지만 파이썬(pip, requests 등)은 기본적으로 OS의 인증서 저장소를 무시하고, certifi라는 자체적인 인증서 패키지를 사용합니다.

이로 인해 다음과 같은 상황에서 충돌이 발생합니다.

1. 사내 보안망 / VPN 환경 (가장 흔함): 특히 회사에서 Zscaler, Cloudflare VPN, Cisco AnyConnect, Fortinet 같은 사내 보안 프록시를 사용 중이라면 이 에러를 마주칠 확률이 99%입니다. 이 보안 모듈들이 트래픽 검사를 위해 자체 사설 인증서를 중간에 끼워 넣는데, 파이썬은 이를 모르기 때문입니다.
2. OS 인증서 동기화 누락: Mac이나 Windows 시스템의 인증서가 파이썬 환경과 제대로 연결되지 않은 경우입니다.

⚠️ 주의: 에러를 피하려고 --trusted-host 옵션을 주거나 코드에 verify=False를 설정하여 SSL 검증을 무시하는 분들이 많습니다. 이는 중간자 공격(MITM)에 시스템을 무방비로 노출시키는 최악의 보안 안티 패턴이므로 절대 권장하지 않습니다.

 

💡 1분 만에 해결하는 가장 완벽한 방법: OS Truststore 연동

우리가 적용할 최고의 해결책은 "파이썬아, OS에 이미 안전하게 등록된 인증서를 가져다 써라"라고 명령하는 것입니다. 터미널을 열고 아래의 명령어를 실행해 주세요.

 

1. 패키지 신규 설치 시

python3 -m pip install pip-system-certs --use-feature=truststore

 

2. 이미 패키지가 있다면 최신 버전으로 업데이트 (-U 옵션)

python3 -m pip install pip-system-certs -U --use-feature=truststore

• pip-system-certs: 파이썬 모듈이 OS의 기본 인증서 저장소를 동적으로 가져다 쓰도록 만들어주는 패키지입니다.
• --use-feature=truststore: pip가 패키지를 다운로드할 때 시스템의 신뢰 저장소를 사용하도록 강제하는 최신 옵션입니다.

⭐ 적용을 위한 재시작 (매우 중요): 설치가 완료되었다면 반드시 현재 사용 중인 터미널이나 IDE(VSCode, PyCharm 등)를 완전히 종료한 후 다시 실행해야 환경이 갱신되어 정상 작동합니다.

 

🛠️ 부록: 환경별 맞춤 트러블슈팅 가이드

위 방법으로도 해결되지 않거나, 특정 환경에서 개발 중이신 분들을 위한 추가 팁입니다.

 

🍎 Mac 사용자 전용 팁 (공식 Python 설치자)

macOS에서 파이썬 공식 홈페이지를 통해 설치하신 분들은 터미널에서 아래 스크립트를 실행하는 것만으로 허무하게 해결되는 경우가 많습니다. (본인의 파이썬 버전에 맞게 숫자를 변경하세요)

/Applications/Python\ 3.11/Install\ Certificates.command

 

💻 PyCharm 사용자 주의사항

PyCharm을 사용 중이시라면 터미널 명령어만으로는 가상환경(venv)에 제대로 적용되지 않을 수 있습니다.

• 해결법: 상단 메뉴에서 [Settings] -> [Project: 프로젝트명] -> [Python Interpreter]로 이동한 뒤, + 버튼을 누르고 pip-system-certs를 검색하여 GUI 환경에서 직접 설치해 주세요.

🏢 사내 인증서를 파이썬 코드에 직접 지정하기

pip install은 되는데, 본인이 작성한 파이썬 스크립트(requests 등) 실행 시 에러가 난다면 사내 인증서(.pem 또는 .crt) 파일 경로를 코드 최상단에 강제로 지정할 수 있습니다.

import os
# 회사 IT팀으로부터 받은 인증서 경로 지정
os.environ['SSL_CERT_FILE'] = 'C:\\.certs\\mycert.pem'

import requests
# 이제 안전하게 외부 API 요청이 가능합니다.
response = requests.get('https://api.example.com')

 

🎯 마무리

평소 삽질 과정에 느낀 점은, "빠르게 에러를 덮어두는 임시방편은 결국 나중에 더 큰 보안 사고로 돌아온다"는 것입니다. 오늘 소개해 드린 방법은 시스템 보안 정책을 준수하면서도 파이썬의 폐쇄적인 인증서 문제를 해결하는 가장 모던한 방식입니다.

 

적용 과정에서 추가적인 에러가 발생하거나 궁금한 점이 있다면 언제든 댓글로 남겨주세요!