Python-dotenv 完全ガイド: .env ファイルで環境変数をスマートに管理！

Python アプリケーションを開発していると、API キー、データベース認証情報、外部サービスの URL など、さまざまな「設定値」を扱う必要があります。これらの情報を直接コードに書き込んでしまうと、セキュリティリスクが高まるだけでなく、開発環境と本番環境で設定を切り替えるのが大変になります。

そこで登場するのが python-dotenv ライブラリです！ このライブラリを使うと、.env という特別なファイルに設定値を記述し、それを Python スクリプトから簡単に読み込むことができます。これにより、コードと設定値を分離し、安全かつ効率的にアプリケーションを管理できるようになります。

この記事では、python-dotenv の基本的な使い方から、応用的なテクニック、ベストプラクティスまで、網羅的に解説します。初心者の方から、すでに利用しているけれどさらに深く知りたい方まで、幅広く役立つ情報をお届けします。

python-dotenv のインストールは非常に簡単です。Python のパッケージ管理ツールである `pip` を使って、以下のコマンドを実行するだけです。

pip install python-dotenv

プロジェクトごとにライブラリのバージョンを管理するために、仮想環境 (venv, conda など) を利用することを強く推奨します。仮想環境内でインストールすることで、他のプロジェクトとの依存関係の衝突を防ぐことができます。

# 仮想環境を作成 (例: venv)
python -m venv myenv
# 仮想環境を有効化 (Windows)
myenv\Scripts\activate
# 仮想環境を有効化 (macOS/Linux)
source myenv/bin/activate
# 仮想環境内で python-dotenv をインストール
pip install python-dotenv

これで、あなたの Python 環境で python-dotenv を利用する準備が整いました！

python-dotenv の最も基本的な使い方は、.env ファイルを作成し、load_dotenv() 関数を呼び出してファイルの内容を環境変数として読み込むことです。

1. `.env` ファイルの作成

まず、Python スクリプトと同じディレクトリ、または親ディレクトリに .env という名前のファイルを作成します。ファイルの中身は、以下のようなキーと値のペア形式で記述します。

.env ファイルの例:

# データベース設定
DATABASE_URL=postgresql://user:password@host:port/database
DATABASE_NAME=mydatabase
# API キー
API_KEY=your_super_secret_api_key
SECRET_KEY=another_secret
# 外部サービス設定
SERVICE_ENDPOINT=https://api.example.com/v1
# コメントは行頭に # を付けます
# DEBUG=True # この行は読み込まれません
# スペースを含む値はクォートなしでもOK (ただし混乱を避けるためクォート推奨)
APP_TITLE=My Awesome Application
# クォートで囲むことも可能
EMAIL_SUBJECT='Hello from App'
ADMIN_EMAIL="admin@example.com"
# 空の値
EMPTY_VAR=

書式のポイント:

• キーと値は = で区切ります。
• キー名は大文字のスネークケース (例: DATABASE_URL) が一般的です。
• 行頭の # はコメントとして扱われ、読み飛ばされます。
• 値にスペースが含まれていても、通常はそのまま記述できます。
• 値をシングルクォート (') またはダブルクォート (") で囲むこともできます。特殊文字や改行を含む場合に便利ですが、必須ではありません。
• 空の値も設定できます (例: EMPTY_VAR=)。

2. Python スクリプトで環境変数を読み込む

次に、Python スクリプト内で python-dotenv をインポートし、load_dotenv() 関数を呼び出します。この関数は、カレントディレクトリまたは親ディレクトリを遡って .env ファイルを探し、見つかったファイルの内容を環境変数としてロードします。

環境変数を読み込んだ後は、標準ライブラリの os モジュールを使って値を取得できます。

main.py (.env と同じディレクトリにある場合):

import os
from dotenv import load_dotenv
# .env ファイルから環境変数を読み込む
# この時点で .env ファイルの内容が環境変数に設定される
load_dotenv()
# 環境変数を取得する
db_url = os.getenv("DATABASE_URL")
api_key = os.getenv("API_KEY")
app_title = os.getenv("APP_TITLE")
empty_var = os.getenv("EMPTY_VAR")
# 存在しないキーを指定すると None が返る
non_existent_var = os.getenv("NON_EXISTENT_VAR")
print(f"データベースURL: {db_url}")
print(f"APIキー: {api_key}")
print(f"アプリタイトル: {app_title}")
print(f"空の変数: '{empty_var}'") # 空文字列 '' が取得される
print(f"存在しない変数: {non_existent_var}")
# os.environ を使ってアクセスすることも可能 (キーが存在しない場合は KeyError が発生する)
try: secret_key = os.environ["SECRET_KEY"] print(f"シークレットキー: {secret_key}")
except KeyError: print("SECRET_KEY は設定されていません。")
try: missing_key = os.environ["MISSING_KEY"]
except KeyError: print("MISSING_KEY は設定されていません。") # こちらが出力される

実行結果の例:

データベースURL: postgresql://user:password@host:port/database
APIキー: your_super_secret_api_key
アプリタイトル: My Awesome Application
空の変数: ''
存在しない変数: None
シークレットキー: another_secret
MISSING_KEY は設定されていません。

ポイント:

• load_dotenv() は、スクリプトのできるだけ早い段階で呼び出すのが一般的です。これにより、他のモジュールがインポートされる前に環境変数が設定されている状態になります。
• os.getenv("キー名", "デフォルト値") のように、第二引数でデフォルト値を指定できます。キーが存在しない場合に None ではなく指定したデフォルト値が返ります。
• os.environ["キー名"] は、キーが存在しない場合に KeyError 例外を送出します。必須の設定値が存在するかどうかをチェックするのに便利です。

これで、基本的な設定値の読み込みは完璧です！

.env ファイルはシンプルな形式ですが、いくつか知っておくと便利なルールや機能があります。

コメント

行頭に # を置くと、その行はコメントとして無視されます。設定の説明などを記述するのに便利です。

# これはコメント行です
KEY=VALUE # 行の途中からのコメントはサポートされていません (VALUE#... として解釈される可能性あり)

クォーテーション (引用符)

値はシングルクォート (') またはダブルクォート (") で囲むことができます。特に、値の先頭や末尾にスペースを含めたい場合や、# を値の一部として扱いたい場合に役立ちます。

SINGLE_QUOTED='Value with leading/trailing spaces '
DOUBLE_QUOTED="Another value with spaces "
# クォートを使わない場合、前後のスペースは通常トリムされます (ライブラリの挙動による場合あり)
NO_QUOTES= Value without explicit quotes
HASH_VALUE="This value contains a # character"

クォートで囲まれた内部のクォート文字は、通常エスケープする必要はありませんが、挙動はライブラリのバージョンや設定によって異なる可能性があるため、注意が必要です。

変数の展開 (Expansion)

.env ファイル内で、他の変数を参照して値を組み立てることができます。${VARIABLE_NAME} または $VARIABLE_NAME の形式で記述します。

BASE_DIR=/path/to/project
LOG_FILE=${BASE_DIR}/logs/app.log
# $変数名 の形式も使える
BACKUP_DIR=$BASE_DIR/backups
# デフォルト値も設定可能 (未定義の場合に使用)
# ${VARIABLE:-default}
UPLOAD_DIR=${UPLOAD_PATH:-${BASE_DIR}/uploads}

注意: 変数展開はデフォルトで有効ですが、load_dotenv(override=False) のように `override=False` を指定すると、既存の環境変数を上書きしないため、展開される変数が期待通りにならない場合があります。

この機能を使うと、共通のパスなどを一箇所で定義して使い回せるため、設定のメンテナンス性が向上します。

複数行の値

値を複数行にわたって記述したい場合は、ダブルクォート (") で囲み、改行をそのまま含めることができます。

PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
MIICXAIBAAKBgQCqGKukO1De7zhZj6+H0qtjTkVxwTCpvKe4eCZ0
... (中略) ...
-----END RSA PRIVATE KEY-----"
MULTI_LINE_MESSAGE="これは一行目です。
これは二行目です。"

Python スクリプトでこれらの値を取得すると、改行文字 (\n) を含んだ文字列として取得されます。

import os
from dotenv import load_dotenv
load_dotenv()
private_key = os.getenv("PRIVATE_KEY")
message = os.getenv("MULTI_LINE_MESSAGE")
print("--- Private Key ---")
print(private_key)
print("\n--- Message ---")
print(message)

エクスポート (Export)

行頭に export キーワードを付けることができます。これは主にシェルスクリプトとの互換性のためのもので、python-dotenv の挙動には通常影響しません。

export EXPORTED_VAR=some_value
NOT_EXPORTED=another_value

どちらの変数も load_dotenv() によって環境変数として読み込まれます。

load_dotenv() 関数は、いくつかの便利な引数を受け付けます。これにより、読み込みの挙動を細かく制御できます。

使用例

特定のパスの `.env` ファイルを読み込み、既存の変数を上書きする:

from dotenv import load_dotenv
import os
# 事前に環境変数を設定しておく (例: OSレベルで設定されている場合)
os.environ['EXISTING_VAR'] = 'original_value'
# 特定のパスにある .env ファイルを指定し、上書きを許可する
dotenv_path = '/path/to/your/custom.env'
load_dotenv(dotenv_path=dotenv_path, override=True, verbose=True)
# custom.env に EXISTING_VAR=new_value があれば上書きされる
print(os.getenv('EXISTING_VAR'))

注意: `override=False` (デフォルト) の場合、もし `os.environ[‘EXISTING_VAR’]` が既に存在していたら、.env ファイルに `EXISTING_VAR` が定義されていても、その値は無視され、元の `original_value` が保持されます。

ファイルが見つからない場合に警告を表示する:

from dotenv import load_dotenv
# 存在しないパスを指定してみる
load_dotenv(dotenv_path='/non/existent/.env', verbose=True)
# -> 標準エラー出力にファイルが見つからない旨のメッセージが表示される

これらのオプションを使いこなすことで、より柔軟な設定管理が可能になります。

python-dotenv は load_dotenv() 以外にも、便利な関数を提供しています。

dotenv_values(): 環境変数を設定せずに辞書として読み込む

load_dotenv() は .env ファイルの内容を直接 os.environ に設定しますが、dotenv_values() は環境変数を変更せず、ファイルの内容を Python の辞書 (dict) として返します。

from dotenv import dotenv_values
import os
# .env ファイルの内容を辞書として取得
config = dotenv_values(".env") # 引数は load_dotenv と同様に指定可能
db_url = config.get("DATABASE_URL")
api_key = config.get("API_KEY")
print(f"データベースURL (from dict): {db_url}")
print(f"APIキー (from dict): {api_key}")
# os.environ には影響を与えない
print(f"環境変数に DB_URL が存在するか: {'DATABASE_URL' in os.environ}") # -> False (load_dotenv を呼んでいない場合)

この関数は、環境変数を直接汚染したくない場合や、設定値をプログラム内でオブジェクトとして扱いたい場合に便利です。

find_dotenv(): `.env` ファイルのパスを探索する

load_dotenv() や dotenv_values() は内部でこの関数を使い、.env ファイルを探しています。この関数を直接使うことで、実際にどの .env ファイルが読み込まれるのかを確認できます。

from dotenv import find_dotenv, load_dotenv
# .env ファイルのパスを探索
# filename: 探すファイル名 (デフォルトは '.env')
# raise_error_if_not_found: 見つからない場合にエラーを送出するか (デフォルトは False)
# usecwd: カレントディレクトリも探索対象に含めるか (デフォルトは False)
try: dotenv_file_path = find_dotenv(raise_error_if_not_found=True, usecwd=True) print(f".env ファイルが見つかりました: {dotenv_file_path}") # 見つかったパスを使って読み込む load_dotenv(dotenv_path=dotenv_file_path)
except IOError: print(".env ファイルが見つかりませんでした。")

探索は、指定された開始ディレクトリ (デフォルトはカレントディレクトリの親) から始まり、親ディレクトリへと遡って行われます。

set_key() と unset_key(): `.env` ファイルをプログラムから編集する

これらの関数を使うと、Python スクリプトから .env ファイルの内容を書き換えることができます。

from dotenv import set_key, unset_key, find_dotenv, get_key
dotenv_path = find_dotenv() # まず .env ファイルのパスを取得
# 新しいキーと値を追加または更新
# set_key(dotenv_path, key_to_set, value_to_set, quote_mode='always', export=False, encoding='utf-8')
# quote_mode: 'always' (常にクォート), 'auto' (必要ならクォート), 'never' (クォートしない)
success, key, value = set_key(dotenv_path, "NEW_VARIABLE", "new_value")
if success: print(f"キー '{key}' を値 '{value}' で設定しました。")
success, key, value = set_key(dotenv_path, "API_KEY", "updated_api_key_123", quote_mode="always")
if success: print(f"キー '{key}' を値 '{value}' で更新しました。")
# .env ファイルからキーを取得する get_key()
current_api_key = get_key(dotenv_path, "API_KEY")
print(f"現在の API_KEY: {current_api_key}") # -> updated_api_key_123
# キーを削除する
# unset_key(dotenv_path, key_to_unset, quote_mode='always', encoding='utf-8')
success, key = unset_key(dotenv_path, "NEW_VARIABLE")
if success: print(f"キー '{key}' を削除しました。")
# 削除されたか確認 (get_key は見つからないと None を返す)
deleted_key_value = get_key(dotenv_path, "NEW_VARIABLE")
print(f"削除後の NEW_VARIABLE: {deleted_key_value}") # -> None

注意: これらの関数は直接 .env ファイルを書き換えます。操作には十分注意し、必要であればバックアップを取るようにしてください。通常、アプリケーションの実行時に設定ファイルを動的に書き換えることは稀で、主に設定管理ツールやデプロイスクリプトなどで利用されることが考えられます。

ストリームからの読み込み

load_dotenv(stream=...) や dotenv_values(stream=...) を使うと、ファイル以外のソース (文字列やネットワーク経由で取得したデータなど) から設定を読み込めます。

import io
from dotenv import load_dotenv, dotenv_values
import os
# 文字列をファイルのように扱う StringIO
dotenv_content = """
STREAM_VAR=Hello from stream!
ANOTHER_STREAM_VAR=12345
"""
stream = io.StringIO(dotenv_content)
# ストリームから読み込んで環境変数に設定
load_dotenv(stream=stream)
print(os.getenv("STREAM_VAR")) # -> Hello from stream!
# ストリームを再度使うために位置を先頭に戻す
stream.seek(0)
# ストリームから読み込んで辞書として取得
config_from_stream = dotenv_values(stream=stream)
print(config_from_stream.get("ANOTHER_STREAM_VAR")) # -> 12345

これにより、設定情報の取得元がファイルシステムに限定されなくなり、より柔軟なシステム構築が可能になります。

python-dotenv は様々な場面で役立ちますが、効果的に使うためにはいくつかのベストプラクティスがあります。

Web フレームワーク (Django, Flask) との連携

Django や Flask などの Web フレームワークでは、設定管理に python-dotenv を導入するのが一般的です。

Flask の例 (app.py):

from flask import Flask
import os
from dotenv import load_dotenv
# アプリケーションの初期化前に .env を読み込む
load_dotenv()
app = Flask(__name__)
# 環境変数から設定を読み込む
app.config['SECRET_KEY'] = os.getenv('SECRET_KEY', 'default-secret-key') # デフォルト値も指定可能
app.config['SQLALCHEMY_DATABASE_URI'] = os.getenv('DATABASE_URL')
app.config['DEBUG'] = os.getenv('DEBUG', 'False').lower() in ('true', '1', 't') # 文字列をboolに変換
@app.route('/')
def index(): return f"Hello! Debug mode is: {app.config['DEBUG']}"
if __name__ == '__main__': # 環境変数からポートを取得 (例) port = int(os.getenv('PORT', 5000)) app.run(host='0.0.0.0', port=port)

Django の例 (settings.py):

import os
from pathlib import Path
from dotenv import load_dotenv
# Build paths inside the project like this: BASE_DIR / 'subdir'.
BASE_DIR = Path(__file__).resolve().parent.parent
# .env ファイルを読み込む (BASE_DIR の親ディレクトリなども探す場合がある)
# プロジェクトルートに .env を置くことが多い
dotenv_path = BASE_DIR.parent / '.env' # or BASE_DIR / '.env' depending on structure
load_dotenv(dotenv_path=dotenv_path)
# Quick-start development settings - unsuitable for production
# See https://docs.djangoproject.com/en/stable/howto/deployment/checklist/
# SECURITY WARNING: keep the secret key used in production secret!
SECRET_KEY = os.getenv('DJANGO_SECRET_KEY', 'fallback-unsafe-secret-key')
# SECURITY WARNING: don't run with debug turned on in production!
DEBUG = os.getenv('DEBUG', 'False').lower() in ('true', '1', 't')
ALLOWED_HOSTS = os.getenv('DJANGO_ALLOWED_HOSTS', '127.0.0.1,localhost').split(',')
# Database
# https://docs.djangoproject.com/en/stable/ref/settings/#databases
DATABASES = { 'default': { 'ENGINE': 'django.db.backends.postgresql', # 例 'NAME': os.getenv('DB_NAME'), 'USER': os.getenv('DB_USER'), 'PASSWORD': os.getenv('DB_PASSWORD'), 'HOST': os.getenv('DB_HOST'), 'PORT': os.getenv('DB_PORT'), }
}
# 他の設定も同様に os.getenv() で読み込む
# ...

フレームワークの設定ファイルのできるだけ早い段階で `load_dotenv()` を呼び出すのがポイントです。

Docker 環境での利用

Docker コンテナ内でアプリケーションを実行する場合でも、python-dotenv は有効です。開発中は .env ファイルをコンテナにマウントまたはコピーして利用し、本番環境では Docker の環境変数機能 (docker run -e や docker-compose.yml の environment) を使って設定を注入するのが一般的です。

Dockerfile (開発用例):

FROM python:3.10-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
# .env ファイルが存在することを前提とする (docker-compose.yml などでマウントする)
# CMD ["python", "main.py"] など、アプリケーションの起動コマンド
# 開発中は load_dotenv() が .env を読む
# 本番環境向けには .env を含めず、環境変数を外部から注入する
# 例: docker run -e API_KEY='prod_key' ... myapp

load_dotenv() は、override=False (デフォルト) の場合、Docker 側で設定された環境変数を優先するため、開発環境 (.env ファイル) と本番環境 (Docker の環境変数) で同じコードベースを使い分けやすくなります。

`.env` ファイルを `.gitignore` に追加する！ (最重要)

.env ファイルには、API キーやパスワードなどの機密情報が含まれることが多いため、絶対に Git などのバージョン管理システムにコミットしてはいけません。

プロジェクトのルートにある .gitignore ファイルに、以下の行を追加してください。

# .gitignore
*.pyc
__pycache__/
myenv/ # 仮想環境フォルダ
*.db
*.sqlite3
# --- 重要 ---
# .env ファイルを除外する
.env

これを忘れると、意図せず機密情報を公開リポジトリなどにプッシュしてしまう危険性があります。非常に重要なので、必ず設定しましょう。

`.env.example` ファイルの活用

.env ファイル自体はコミットしませんが、どのような環境変数が必要なのかを他の開発者や将来の自分に示すために、.env.example (または .env.template など) という名前のファイルを作成し、こちらはコミットするのが良いプラクティスです。

.env.example には、必要なキー名と、ダミーの値や説明を記述します。

.env.example の例:

# このファイルは .env ファイルのテンプレートです。
# 実際の値は .env ファイルに記述し、.gitignore に追加してください。
DATABASE_URL=postgresql://user:password@host:port/database
DATABASE_NAME=
API_KEY= # ここに実際のAPIキーを入力
SECRET_KEY= # アプリケーションのシークレットキー
DEBUG=False # 開発時は True に設定
SERVICE_ENDPOINT=https://api.example.com/v1

新しい開発者がプロジェクトに参加した際、この .env.example をコピーして .env を作成し、必要な値を埋めるだけで環境構築が完了します。

本番環境での環境変数管理

開発中は .env ファイルが便利ですが、本番環境ではセキュリティや管理の観点から、異なる方法で環境変数を設定することが推奨されます。

• OS の環境変数: サーバー自体に環境変数を設定する。デプロイ手順に組み込む必要があります。
• コンテナオーケストレーションツール (Kubernetes, Docker Swarm): Secret や ConfigMap などの機能を使って環境変数を注入する。
• PaaS (Heroku, AWS Elastic Beanstalk など): プラットフォームが提供する環境変数設定機能を利用する。
• 設定管理ツール (AWS Systems Manager Parameter Store, HashiCorp Vault など): より高度なシークレット管理機能を提供するツールを利用する。

python-dotenv は override=False がデフォルトなので、本番環境でこれらの方法で設定された環境変数は、もし誤って .env ファイルがデプロイされてしまっても上書きされず、本番用の設定が優先されるため、安全策としても機能します。

python-dotenv を使う上で、いくつか注意すべき点や、問題が発生した場合の対処法があります。

ファイルが見つからない / 読み込まれない

• 実行場所と .env の位置関係: load_dotenv() は、デフォルトではスクリプトの実行場所ではなく、find_dotenv() が見つけたパス (通常はカレントディレクトリか親ディレクトリ) の .env を読み込みます。スクリプトの実行場所が想定と違う場合、読み込まれないことがあります。
  • 対策: load_dotenv(dotenv_path='/path/to/.env') で明示的にパスを指定するか、load_dotenv(verbose=True) でどのパスを探しているか確認します。
• ファイル名のタイポ: ファイル名が .env になっているか確認します (例: env, .env.txt などになっていないか)。
• load_dotenv() の呼び出しタイミング: 環境変数を参照するコードよりも前に load_dotenv() が呼び出されているか確認します。特に、モジュールのトップレベルで環境変数を使っている場合、そのモジュールがインポートされる前に load_dotenv() を実行する必要があります。アプリケーションのエントリーポイント (app.py や manage.py の最初など) で呼び出すのが一般的です。

環境変数が期待通りに上書きされない

• override オプション: デフォルト (override=False) では、既に OS レベルなどで設定されている環境変数は .env ファイルの値で上書きされません。意図的に上書きしたい場合は load_dotenv(override=True) を使用します。

特殊文字やクォートの扱い

• 値に # や = を含める: 値にこれらの文字を含めたい場合は、値をクォート ("..." または '...') で囲むのが安全です。
• 変数の展開 ($): 値の中で $ 文字をリテラルとして使いたい場合 (変数展開を意図しない場合)、\$ のようにエスケープするか、全体をシングルクォートで囲む ('...') などの方法があります (挙動はバージョンによる可能性あり)。または load_dotenv(interpolate=False) で変数展開自体を無効にする方法もあります。

ライブラリのバージョン

稀に、ライブラリのバージョン間で細かい挙動 (クォートの解釈、変数展開の方法など) が変更される可能性があります。もし予期せぬ動作に遭遇した場合は、使用している python-dotenv のバージョンを確認し、公式ドキュメントやリリースノートを参照してみてください。

pip show python-dotenv

問題が発生した場合は、load_dotenv(verbose=True) を有効にしてデバッグ情報を確認するのが第一歩です。

python-dotenv は、Python アプリケーションにおける設定管理を劇的に改善してくれるシンプルかつ強力なライブラリです。

主なメリット:

• 設定とコードの分離: 機密情報や環境依存の設定をコードから切り離せる。
• セキュリティ向上: API キーなどを誤ってバージョン管理にコミットするリスクを低減 (.gitignore との併用が前提)。
• 環境間の簡単な切り替え: 開発、ステージング、本番環境ごとに .env ファイルを用意 (または環境変数で上書き) するだけで設定を切り替えられる。
• チーム開発の効率化: .env.example を使って必要な設定項目を共有できる。
• 導入の容易さ: `pip install` して `load_dotenv()` を呼び出すだけですぐに使える。

.env ファイルの書式、load_dotenv() のオプション、関連関数 (dotenv_values, find_dotenv など) を理解し、.gitignore への追加や .env.example の活用といったベストプラクティスを実践することで、より安全でメンテナンス性の高い Python アプリケーションを構築できます。

まだ導入していない方は、ぜひ次のプロジェクトから python-dotenv を活用してみてください！きっと開発体験が向上するはずです。Happy coding!