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.

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.
# .env
DATABASE_URL=postgres://localhost:5432/app
DEBUG=falseimport os
from dotenv import load_dotenv
os.environ["DATABASE_URL"] = "postgres://remote:5432/prod"
load_dotenv()
print(os.environ["DATABASE_URL"])
# postgres://remote:5432/prodThe 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"])
# falseThe 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:
- Process environment variables (set by the shell, orchestrator, or CI)
.envfile contents- 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 layer an environment-specific file on top.
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.
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:
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"))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 toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.