python .env 파일 안읽힘 해결 방법과 실무 가이드

python .env 파일 안읽힘이 필요한 상황

python .env 파일 안읽힘 현상을 만났을 때는 개발 또는 배포 환경에서 환경변수가 예상처럼 적용되지 않아 서비스가 실패하거나 비밀키가 노출되는 위험이 있습니다. 이 글에서는 원인 진단법, 코드 기반 해결법, 배포 시 고려사항과 실무 체크리스트를 제공해 즉시 고칠 수 있도록 돕습니다.

python .env 파일 안읽힘 핵심 개념

.env 파일은 일반적으로 키=값 형태로 환경 변수를 저장하는 텍스트 파일입니다. Python 프로젝트에서는 보통 python-dotenv 패키지의 load_dotenv 또는 Django의 django-environ 등을 사용해 .env 파일을 읽습니다. 하지만 파일 경로 문제, 권한, 가상환경과 프로세스 시작 위치, 운영체제의 환경 우선순위 등으로 인해 .env 파일이 로드되지 않을 수 있습니다. 주요 원인은 다음과 같습니다:

현재 작업 디렉터리와 .env 파일 위치 불일치
load_dotenv 호출 시점이 늦음 (환경 변수를 사용하기 전에 호출해야 함)
운영환경(예: systemd, Docker, Heroku)의 환경변수 우선순위
파일 인코딩 또는 줄 끝 문제
소스 제어에서 .env 누락

python dotenv와 load_dotenv 사용법 (예제 포함)

아래는 python-dotenv를 사용해 .env 파일을 명시적으로 로드하는 기본 예제입니다. 이 코드는 프로젝트 루트의 .env를 읽고 os.environ에 값들을 추가합니다.

# app/config.py
import os
from pathlib import Path
from dotenv import load_dotenv

BASE_DIR = Path(__file__).resolve().parent.parent
env_path = BASE_DIR / '.env'

# 항상 앱 시작 직후 호출: 다른 모듈에서 환경변수를 사용하기 전에 로드
load_dotenv(dotenv_path=env_path)

SECRET_KEY = os.getenv('SECRET_KEY')
DEBUG = os.getenv('DEBUG', 'false').lower() in ('1', 'true')

# 사용 예
if not SECRET_KEY:
    raise RuntimeError('SECRET_KEY가 설정되지 않았습니다.')

주의: load_dotenv()를 호출하지 않거나 잘못된 경로를 넘기면 변수가 안 읽힙니다.

python .env 파일 안읽힘 실무 예제과 트러블슈팅

실무에서 자주 보이는 시나리오와 해결 방법을 단계별로 정리합니다.

로컬 개발: 가상환경 활성화 후 앱을 실행했는데 설정이 적용되지 않는 경우

원인: 앱을 실행하는 스크립트가 프로젝트 루트가 아닌 다른 경로에서 실행됨
해결: Path 기반으로 .env 경로를 계산하거나 실행 스크립트에서 cwd를 변경

Docker 컨테이너: .env를 빌드 타임에 복사했지만 런타임에 변하지 않음

원인: 컨테이너 빌드 시점과 런타임 환경변수 우선순위 혼동
해결: Dockerfile에서 COPY로 .env를 넣기보다 docker-compose 또는 kubernetes secret/configmap으로 주입

systemd 서비스: 서비스로 띄운 프로세스에서 .env가 무시됨

원인: systemd는 서비스 단위로 EnvironmentFile을 사용하거나 ExecStart 환경에서 cwd가 다름
해결: systemd 서비스 파일에 EnvironmentFile=<경로> 또는 ExecStartPre에서 로드

실무 코드 예시 (Docker에서의 권장 접근):

# docker-compose.yml 예시 (일부)
version: '3.8'
services:
  web:
    image: myapp:latest
    env_file:
      - .env
    command: gunicorn myapp.wsgi:application --bind 0.0.0.0:8000

언제 쓰면 좋고 언제 피해야 할까

언제 쓰면 좋은가

로컬 개발 환경에서 빠르게 환경변수를 관리할 때
작은 팀, 비밀키를 별도 시크릿 스토어로 관리하지 않을 때 테스트용으로

언제 피해야 하는가

프로덕션 비밀키를 소스나 이미지에 포함해야 하는 경우
대규모 분산 시스템에서 중앙화된 시크릿 관리가 필요한 경우 (Vault, KMS 등 사용 권장)

비교표: .env 직접 사용 vs 시크릿 매니저

구분	항목1	항목2	항목3
내용	로컬 편의성	보안 수준	운영 복잡도
직접 .env	매우 간편, 개발 친화적	낮음, 파일 유출 위험	낮음, 단일 파일 관리
시크릿 매니저	설정 필요	높음, 감사·회전 지원	중간~높음, 인프라 연동 필요

실무 체크리스트

.env 파일 경로를 절대/프로젝트 기준으로 계산했는가?
load_dotenv 또는 환경 로드 코드를 앱 시작 시 가장 먼저 실행하는가?
서비스(예: systemd, Docker, k8s) 설정에 환경 주입 방법이 올바른가?
.env가 .gitignore에 포함되어 소스에 노출되지 않는가?
파일 인코딩은 UTF-8이고 줄 끝이 CRLF/ LF 문제 없는가?
운영환경에서는 시크릿 매니저 도입을 검토했는가?

성능·보안·운영 주의점

성능

.env 파일 로딩 자체는 매우 경량이며 성능 문제가 되지 않습니다. 다만 애플리케이션이 부하 상태에서 파일을 반복적으로 읽는 구조는 피하십시오.

보안

절대 프로덕션 시크릿을 깃 저장소에 커밋하지 마세요.
.env 파일 권한을 600으로 제한하고 서버에 저장 시 접근 제어를 강화하세요.
가능한 경우 플랫폼 시크릿 매니저(AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault 등)를 사용하세요.

운영

컨테이너 이미지에 .env를 포함시키는 대신 런타임에 주입하세요.
배포 파이프라인에서 환경값을 주입하는 절차를 문서화하고 감사 로그를 남기세요.

추가 실무 코드 예시: Django에서 django-environ 사용

# settings.py (일부)
import environ
from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent
env = environ.Env(
    DEBUG=(bool, False)
)
# .env 파일 경로 명시
environ.Env.read_env(BASE_DIR / '.env')

SECRET_KEY = env('SECRET_KEY')
DEBUG = env('DEBUG')

자주 묻는 질문

Q1: .env 파일을 무조건 사용해야 하나요? A1: 아니요. 로컬 개발에는 편리하지만 프로덕션에서는 시크릿 매니저 사용을 권장합니다.

Q2: load_dotenv를 여러 번 호출해도 문제가 있나요? A2: 일반적으로 중복 호출은 큰 문제가 없지만, 값 덮어쓰기 정책을 명확히 해야 합니다. load_dotenv는 기본적으로 기존 환경변수를 덮어쓰지 않습니다(override=True 옵션 사용 시 덮어씀).

Q3: Docker에서 .env 파일 대신 ENV에 직접 값을 쓰면 되나요? A3: 가능하지만 민감정보는 이미지에 하드코딩하지 마시고 런타임에 주입하거나 시크릿 매니저를 사용하세요.

Q4: .env 파일이 있는데도 값이 없다고 나옵니다. 어디서부터 확인하죠? A4: 1) 앱이 실행되는 현재 작업 디렉터리 확인 2) load_dotenv 호출 위치 확인 3) 파일 인코딩과 줄 끝 확인 4) 권한 및 소유자 확인 5) 운영 플랫폼 환경 우선순위 확인

정리

python .env 파일 안읽힘 문제는 경로, 호출 시점, 운영환경 우선순위가 주요 원인입니다.
load_dotenv 또는 django-environ을 앱 시작 시 가장 먼저 호출하세요.
프로덕션 환경에서는 시크릿 매니저 사용을 권장합니다.
배포 파이프라인과 컨테이너 런타임에서 환경 변수 주입 방식을 통일하세요.
실무 체크리스트를 통해 로컬·배포 환경 모두 점검해 오류를 예방하세요.