AI 생성 이미지: 성인 개발자가 노트북과 모니터를 번갈아 확인하며 실행 환경 차이를 점검하는 장면

파이썬 환경변수가 안 읽힐 때: os.getenv() None 원인과 확인 순서

by

os.getenv()가 None을 반환하면 먼저 Python 코드보다 실행 프로세스에 해당 키가 실제로 전달됐는지 확인해야 합니다. 터미널의 export 누락, .env 미로드, 다른 작업 폴더나 IDE·예약 실행 환경이 대표적인 원인입니다. 재설치나 코드 재작성 전에 아래 순서로 원인을 좁히면 확인 범위를 불필요하게 넓히지 않을 수 있습니다.

먼저 확인할 것은 키가 아니라 실행 환경입니다

Python의 os.environ은 프로세스가 시작될 때의 환경변수 매핑을 반영하고, os.getenv()는 그 환경을 바탕으로 값을 찾습니다. 따라서 한 터미널에서 값을 설정했다고 해서 다른 터미널, IDE, 예약 실행 프로세스에도 자동으로 전달되는 것은 아닙니다.

비밀값을 출력해 확인하는 방식은 피하고, 진단할 때는 존재 여부만 제한적으로 확인합니다.

import os

key = "API_KEY"
value = os.getenv(key)

print({"key": key, "present": value is not None, "length": len(value) if value else 0})

이 출력은 값 자체를 보여주지 않으면서 현재 프로세스가 키를 받았는지 확인하는 데 도움을 줍니다.

os.getenv()의 None과 os.environ[]의 오류를 구분합니다

os.getenv("API_KEY")는 키가 없을 때 기본값인 None을 반환합니다. 그래서 아래처럼 곧바로 인증 요청을 보내면, 실제 원인이 환경변수 누락인데도 뒤에서 인증 실패처럼 보일 수 있습니다.

import os

api_key = os.getenv("API_KEY")
if api_key is None:
    raise RuntimeError("필수 환경변수 API_KEY가 없습니다.")

반면 os.environ["API_KEY"]처럼 대괄호로 접근하면 필수 키가 없을 때 즉시 예외가 발생합니다. 설정이 반드시 필요한 자동화라면 이 방식이 누락을 빠르게 드러낼 수 있고, 선택 설정이라면 getenv()와 명시적인 기본값 또는 조건문이 더 자연스럽습니다.

셸에서 설정했지만 Python이 못 읽는 경우

현재 셸에서 변수에 값을 대입한 것과 자식 프로세스에 전달하는 것은 다를 수 있습니다. IDE의 실행 버튼이나 예약 실행기는 로그인 셸과 다른 환경에서 시작될 수 있으므로, 터미널에서 동작했다는 사실만으로 같은 결과를 기대하기 어렵습니다.

확인 순서는 다음과 같습니다.

  1. 코드에서 읽는 키 이름과 설정한 이름의 철자를 비교합니다.
  2. Python을 실행한 동일한 터미널 세션에서 키의 존재 여부를 확인합니다.
  3. IDE·서비스·예약 실행기에서 별도로 환경변수를 전달하도록 설정했는지 확인합니다.
  4. 각 실행 방식에서 현재 작업 폴더와 Python 실행 경로가 같은지 비교합니다.

subprocess로 다른 프로그램을 실행하는 경우에도 별도 env를 지정했는지에 따라 자식 프로세스가 받는 환경이 달라질 수 있습니다.

.env 파일은 호출 시점과 경로가 중요합니다

.env 파일을 프로젝트에 두었다고 해서 Python 표준 라이브러리가 자동으로 읽어 주는 것은 아닙니다. python-dotenv를 사용한다면 실제 설정값을 읽는 코드보다 앞에서 load_dotenv()를 호출해야 합니다.

from dotenv import load_dotenv
import os

load_dotenv()
api_key = os.getenv("API_KEY")

경로가 실행 위치에 따라 달라지는 자동화라면 .env가 어디에서 발견되는지 확인하고, 필요하면 dotenv_path를 명시합니다. load_dotenv()는 기존 시스템 환경변수를 기본적으로 덮어쓰지 않으므로, 셸에 이미 같은 키가 있으면 .env의 값이 선택되지 않을 수 있습니다.

.env 파일을 저장소에 커밋하거나 로그에 내용을 남기지 않도록 관리해야 합니다. 파일을 읽는 데 성공했는지 확인하는 것과 비밀값을 공개하는 것은 다른 문제입니다.

원인을 판별한 뒤 설정 방식을 선택합니다

환경변수 자체가 없는지, 셸에서 자식 프로세스로 전달되지 않았는지, .env 로드가 늦었는지, 실행 위치가 달라 파일을 찾지 못했는지를 구분하면 선택도 쉬워집니다.

  • 여러 실행기가 공통으로 읽어야 하는 값이면 각 실행기에서 환경변수 전달 방식을 명시합니다.
  • 개발용 로컬 설정을 파일로 관리한다면 .env 로드 시점과 경로를 고정하고 비밀 파일을 보호합니다.
  • 필수값이면 시작 단계에서 존재 여부를 검사해 모호한 후속 오류를 막습니다.
  • 터미널과 IDE·예약 실행의 결과가 다르면 두 프로세스의 작업 폴더, 실행 경로, 환경 전달 설정을 비교합니다.

키가 존재하는데도 외부 API 인증이 실패한다면, 그때는 인증 방식이나 서비스 측 조건을 별도의 문제로 분리해 확인해야 합니다.

참고 자료

다음으로는 파이썬 환경변수가 안 읽힐 때 os.getenv·.env·예약 실행 확인법에서 실행 방식별 점검 항목을 이어서 살펴볼 수 있습니다.

Leave a Comment