파이썬에서 .env 환경변수가 None이거나 수정한 값이 반영되지 않는다면 파일 위치, 로드 시점, 기존 환경변수 우선순위, 실행 중인 프로세스를 차례로 확인하면 됩니다. 핵심은 os.getenv() 자체를 의심하기보다 load_dotenv()가 어느 파일을 언제 읽었는지와 이미 프로세스에 들어온 값의 출처를 구분하는 것입니다. 이 글에서는 네 가지 점검 순서와 필수 설정값을 안전하게 확인하는 방법을 정리합니다.
1. 실제로 찾는 .env 경로부터 확인하기
경로를 지정하지 않은 load_dotenv()는 find_dotenv()를 사용해 .env를 찾습니다. 공식 레퍼런스에 따르면 이 검색은 상위 디렉터리 방향으로 진행되며 파일을 찾지 못하면 빈 문자열을 반환할 수 있습니다. 터미널에서는 되는데 VS Code, Jupyter, 예약 실행에서 실패한다면 실행 방식에 따라 현재 위치나 검색 기준이 달라졌을 가능성을 먼저 봅니다.
진단할 때는 비밀값을 출력하지 말고 파일이 발견됐는지만 확인합니다.
from dotenv import find_dotenv, load_dotenv
env_path = find_dotenv()
print(".env 발견 여부:", bool(env_path))
print(".env 경로:", env_path or "찾지 못함")
loaded = load_dotenv(env_path or None)
print("로드 시도 결과:", loaded)
프로젝트 구조가 고정되어 있다면 상대 경로에 기대기보다 경로를 명시하는 편이 진단과 운영 모두에서 분명합니다. 다만 경로를 명시해도 파일이 배포 환경에 실제로 존재하는지는 별도로 확인해야 합니다.
2. load_dotenv()를 값 사용보다 먼저 호출하기
load_dotenv()는 os.getenv()나 os.environ을 읽는 코드보다 먼저 실행해야 합니다. 모듈 import 과정에서 환경변수를 상수로 저장하거나 클라이언트를 만들면, 나중에 .env를 로드해도 이미 만들어진 객체에는 새 값이 반영되지 않을 수 있습니다.
import os
from dotenv import load_dotenv
load_dotenv()
api_key = os.getenv("API_KEY")
if not api_key:
raise RuntimeError("API_KEY가 설정되지 않았습니다.")
실무에서는 애플리케이션 진입점에서 한 번 로드한 뒤 설정 검증을 통과한 값만 다른 모듈로 넘기는 방식이 추적하기 쉽습니다. None을 뒤늦게 발견하는 것보다 시작 단계에서 중단하는 편이 예약 작업이나 자동화 로그를 해석하기도 좋습니다.
3. 기존 OS 환경변수가 .env보다 우선하는지 확인하기
load_dotenv()의 override 기본값은 False이므로 같은 이름의 기존 환경변수가 있으면 .env 값으로 덮어쓰지 않습니다. 운영 셸, IDE 실행 설정, 노트북 커널에 같은 이름이 이미 들어 있다면 파일을 수정해도 예전 값처럼 보일 수 있습니다.
from dotenv import load_dotenv
# 기존 환경변수를 유지하는 기본 동작
load_dotenv()
# 정말로 .env 값을 우선할 때만 명시적으로 선택
# load_dotenv(override=True)
override=True는 편리하지만 실행 환경이 의도적으로 주입한 값을 바꿀 수 있습니다. 따라서 개발용 .env를 항상 우선할지, 배포 환경의 환경변수를 우선할지 먼저 결정하고 한 곳에서만 정책을 적용하는 편이 안전합니다.
4. 이미 실행 중인 프로세스인지 확인하기
Python의 os.environ은 os 모듈이 처음 import될 때의 환경을 매핑으로 캡처하고, os.getenv()는 그 매핑을 사용합니다. 따라서 .env 파일을 수정했다고 해서 이미 실행 중인 Python 프로세스의 변수와 그 변수로 생성된 객체가 자동으로 갱신된다고 가정하면 안 됩니다.
노트북에서는 커널을 재시작하거나 로드 코드를 다시 실행할 시점을 확인하고, 예약 작업은 실행마다 초기화 코드가 호출되는지 점검합니다. 장시간 실행 프로세스라면 .env 재로드보다 설정 변경을 어떤 방식으로 반영할지 운영 정책으로 정하는 것이 먼저입니다.
빠른 판단표
| 증상 | 먼저 확인할 것 | 다음 판단 |
|---|---|---|
os.getenv()가 None |
find_dotenv() 결과와 load_dotenv() 호출 위치 |
파일 경로를 명시하거나 시작 단계로 이동 |
.env를 고쳐도 값이 그대로임 |
같은 이름의 OS 환경변수와 override 설정 |
우선순위를 결정하고 프로세스를 재시작 |
| 터미널과 IDE 결과가 다름 | IDE의 실행 위치와 환경변수 설정 | 실행 환경별 초기화 방식을 통일 |
| 예약 작업에서만 실패함 | 작업이 시작될 때 .env를 읽는지 |
절대·기준 경로와 필수값 검증을 함께 설정 |
마무리: 값이 아니라 로딩 경로와 수명부터 추적하기
이 문제는 대개 os.getenv() 문법보다 파일을 찾는 기준, 로드 호출 시점, 기존 환경변수의 우선순위, 프로세스 수명의 차이에서 생깁니다. 먼저 비밀값을 출력하지 않고 .env 발견 여부와 로드 결과만 확인한 뒤, 필수값 검증을 시작 지점에 두면 원인을 빠르게 좁힐 수 있습니다.
API 키 같은 비밀값은 .env에 두더라도 저장소에 커밋하지 않고 실행 환경의 비밀 관리 방식을 함께 확인해야 합니다. 다음으로는 예약 작업의 현재 작업 폴더와 필수 환경변수 검증 방식을 별도의 점검 항목으로 정리해 두면 좋습니다.