[Python] .env 파일로 환경 변수 완벽하게 관리하기 (보안과 효율성 잡기)

1. 왜 .env 파일을 써야 할까?

개발을 하다 보면 다음과 같은 고민을 하게 될 때가 있습니다.

• "이 API 키를 코드에 그대로 적어서 GitHub에 올려도 될까?"
• "개발 서버랑 운영 서버의 DB 주소가 다른데, 매번 코드를 수정해야 하나?"

민감한 정보(Secret Key, DB Password)를 소스 코드 내부에 직접 하드코딩하는 것은 보안상 최악의 선택입니다. 실수로 GitHub 같은 공개 저장소에 올리는 순간, 해커들의 먹잇감이 되기 때문이죠. 또한, 배포 환경에 따라 설정을 유연하게 바꾸기 위해서라도 설정과 코드는 분리되어야 합니다.

이때 가장 널리 사용되는 표준적인 방법이 바로 .env 파일과 환경 변수(Environment Variable)를 사용하는 것입니다.

2. 핵심 도구: python-dotenv

파이썬에서는 .env 파일에 정의된 변수들을 마치 시스템 환경 변수처럼 로드해 주는 라이브러리인 python-dotenv를 주로 사용합니다.

1) 라이브러리 설치

먼저 터미널에서 라이브러리를 설치합니다.

pip install python-dotenv

2) .env 파일 생성

프로젝트 최상위 경로(루트 디렉터리)에 .env라는 이름의 파일을 만들고, 관리하고 싶은 변수들을 KEY=VALUE 형태로 작성합니다.
(주의: 띄어쓰기 없이 작성하는 것이 원칙입니다.)

# .env 파일 예시
OPENAI_API_KEY=sk-1234567890abcdefg
DB_HOST=localhost
DB_PORT=3306
DEBUG_MODE=True

3. 파이썬 코드에서 불러오기

이제 파이썬 코드에서 이 값들을 불러와 보겠습니다. 사용법은 매우 간단합니다.

import os
from dotenv import load_dotenv

# 1. .env 파일 로드 (환경 변수로 등록됨)
load_dotenv() 

# 2. os.getenv를 사용하여 값 가져오기
api_key = os.getenv("OPENAI_API_KEY")
db_host = os.getenv("DB_HOST")

print(f"API Key: {api_key}")
print(f"DB Host: {db_host}")

• load_dotenv(): 현재 디렉터리의 .env 파일을 찾아 환경 변수로 설정합니다.
• os.getenv("KEY"): 해당 키의 값을 가져옵니다. 만약 키가 없다면 None을 반환하므로 에러 처리가 용이합니다.

4. 가장 중요한 점: .gitignore 설정

.env 파일을 쓰는 가장 큰 이유는 보안입니다. 그런데 이 파일을 GitHub에 그대로 올려버리면 아무 소용이 없겠죠?

반드시 .gitignore 파일에 .env를 추가하여 버전 관리 시스템이 이 파일을 무시하도록 설정해야 합니다.

# .gitignore 파일
.env
.venv
__pycache__/

대신, 협업하는 동료들을 위해 .env.template 또는 .env.example 파일을 만들어 공유하는 것이 좋습니다. 여기에는 실제 값은 비워두고 어떤 키값이 필요한지만 명시합니다.

# .env.example (Github에 올려도 됨)
OPENAI_API_KEY=
DB_HOST=
DB_PORT=

5. 심화: pydantic-settings 활용하기 (선택 사항)

프로젝트 규모가 커지면 단순히 os.getenv만으로는 부족할 수 있습니다. 타입 검증(Type Checking)과 관리를 더 체계적으로 하고 싶다면 pydantic-settings를 추천합니다.

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    OPENAI_API_KEY: str
    DB_PORT: int = 3306  # 기본값 설정 가능

    class Config:
        env_file = ".env"

settings = Settings()

# 사용
print(settings.OPENAI_API_KEY)

이렇게 하면 DB_PORT가 숫자가 아니거나 필수 키가 누락되었을 때, 앱 실행 시점에 바로 에러를 띄워주어 훨씬 안전한 개발이 가능합니다.

마무리

오늘은 파이썬 프로젝트에서 .env 파일을 활용해 환경 변수를 관리하는 방법에 대해 알아보았습니다.

1. python-dotenv 설치
2. .env 파일에 비밀 정보 작성
3. os.getenv로 호출
4. .gitignore에 .env 등록 (필수!)