Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Overriding .env Values with python-dotenv

Learn how python-dotenv handles overrides in .env files, including default behavior, override=True, precedence, set_key, and dotenv_values.

~4 min readPython
#python-dotenv#environment variables#configuration management#.env files
Illustration of python-dotenv overriding environment variable values from a .env file.

When you load a .env file with python-dotenv, the default behavior is to not overwrite environment variables that already exist in the process. This deliberate safety measure often confuses developers who expect the file to act as the source of truth. Understanding how override works is essential for building predictable configuration loading in Python applications.

How python-dotenv Handles Existing Environment Variables

The core function load_dotenv() reads a .env file and sets variables into os.environ. By default, it uses override=False. That means if a variable is already present in the environment, the value from the .env file is ignored.

python
# .env DATABASE_URL=postgres://localhost:5432/app DEBUG=false
python
import os from dotenv import load_dotenv os.environ["DATABASE_URL"] = "postgres://remote:5432/prod" load_dotenv() print(os.environ["DATABASE_URL"]) # postgres://remote:5432/prod

The existing DATABASE_URL wins because load_dotenv() does not override. This behavior prevents accidental clobbering of variables set by the shell, CI system, or container runtime.

Using override=True to Replace Values

When you explicitly want the .env file to take precedence, pass override=True.

python
from dotenv import load_dotenv load_dotenv(override=True)

Now any variable defined in the .env file will replace an existing environment variable with the same name.

python
import os from dotenv import load_dotenv os.environ["DEBUG"] = "true" load_dotenv(override=True) print(os.environ["DEBUG"]) # false

The override parameter applies to every variable in the file. There is no built-in way to override only a subset of variables while respecting others; you need to handle that manually if required.

Precedence Rules and Why Override Matters

Configuration precedence is a common source of bugs. In a typical deployment, you have multiple sources of configuration, each with a different priority:

  1. Process environment variables (set by the shell, orchestrator, or CI)
  2. .env file contents
  3. Default values in code

With override=False, the process environment wins over .env. With override=True, the .env file wins. Choosing the right mode depends on where you want the authoritative configuration to live.

For local development, override=True is often convenient because it ensures the .env file always matches what the code sees, even if your shell has a conflicting variable. For production, override=False is safer because it lets the deployment platform inject secrets without being overridden by a file that might be accidentally committed.

Configuration Patterns for Different Environments

A common pattern is to use separate files for different environments, such as .env, .env.local, .env.production. You can load them conditionally based on an environment variable like APP_ENV.

python
import os from dotenv import load_dotenv env = os.getenv("APP_ENV", "development") if env == "production": load_dotenv(".env.production", override=False) else: load_dotenv(".env.local", override=True)

This gives you fine-grained control. In development, you might want the local file to override shell variables; in production, you want the platform environment to take precedence.

Another approach is to load a base .env and then layer an environment-specific file on top.

python
load_dotenv(".env") load_dotenv(f".env.{os.getenv('APP_ENV', 'development')}", override=True)

The first call loads the base file without overriding any pre-existing environment variables. The second call lets the environment-specific file override both the base file and any variables already in os.environ, because it uses override=True.

Overriding Values Programmatically with set_key

Sometimes you need to update the .env file itself, not just the runtime environment. python-dotenv provides set_key to write or update a key in a .env file.

python
from dotenv import set_key set_key(".env", "API_KEY", "new-secret-value")

set_key does not have an override parameter; it writes or updates the key unconditionally. It updates the file in place, preserving comments and other keys. The quote_mode parameter controls how values are quoted, not whether an existing value is overwritten.

If you need to update only when the key is missing, check first:

python
from dotenv import dotenv_values, set_key values = dotenv_values(".env") if "API_KEY" not in values: set_key(".env", "API_KEY", "default-value")

This is useful for bootstrapping configuration without clobbering manually set values.

Common Pitfalls and Operational Considerations

One frequent mistake is assuming load_dotenv() will override variables set in the shell. It won't unless you pass override=True. This leads to confusing behavior where a .env file appears to be ignored.

Another pitfall is using override=True in production, which can cause a committed .env file to override secrets injected by the deployment platform. This is a security risk because it can silently switch the app to unintended credentials.

When working with multiple .env files, remember that each load_dotenv() call operates on the current os.environ. If you call load_dotenv() twice without override, the second call will not overwrite values set by the first. To layer files, use override=True on subsequent calls.

Finally, be aware that dotenv_values() reads the file without modifying os.environ. It is useful for inspection or for building a configuration dictionary without side effects.

python
from dotenv import dotenv_values config = dotenv_values(".env") print(config.get("DATABASE_URL"))

Unlike load_dotenv, dotenv_values does not modify os.environ; it returns a dictionary of values parsed from the file. It also has no override parameter. That is an important distinction: load_dotenv merges with the environment, while dotenv_values parses the file.

Understanding these behaviors lets you choose the right tool for each configuration task. For runtime environment setup, use load_dotenv with the appropriate override flag. For reading configuration without side effects, use dotenv_values. For updating the file, use set_key. Each function serves a distinct purpose, and knowing when to override values is the key to predictable configuration management.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.