Python Dotenv Override Values and Configuration

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 is a deliberate safety measure, but it often confuses developers who expect the file to act as the source of truth. Understanding how python dotenv override values and configuration 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.

# .env
DATABASE_URL=postgres://localhost:5432/app
DEBUG=false

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.

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.

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.

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 load an environment-specific file with override=True to layer values.

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

This lets the environment-specific file override the base file, but still respects pre-existing environment variables unless you use override=True on the second call.

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.

from dotenv import set_key

set_key(".env", "API_KEY", "new-secret-value")

By default, set_key will not overwrite an existing key unless you pass quote_mode="always" or use the override parameter? Actually, set_key does not have an override parameter; it always writes the value. But you can use quote_mode to control quoting. The function updates the file in place, preserving comments and other keys.

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

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.

from dotenv import dotenv_values

config = dotenv_values(".env")
print(config.get("DATABASE_URL"))

This function also respects the same override semantics? Actually, dotenv_values always returns the file's values regardless of the current environment; it does not consider existing environment variables. That is an important distinction: load_dotenv merges with the environment, while dotenv_values simply 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.