Flask Environment Variables and .env Files

Environment variables are the backbone of configurable applications. When you write a Flask app, you want it to behave differently depending on where it runs: on your local machine, on a staging server, or in production. Hardcoding these values is a trap that leads to brittle, unportable code. Instead, environment variables let you externalize configuration.

Flask itself doesn’t come with a magic wand for environment variables, but it’s designed to make it user-friendly them. The key is the os.environ dictionary in Python’s standard library, which holds all environment variables available to the process.

Here’s a minimal example that shows how to retrieve a configuration value from an environment variable:

import os
from flask import Flask

app = Flask(__name__)
app.config['SECRET_KEY'] = os.environ.get('SECRET_KEY', 'default-secret')

@app.route('/')
def index():
    return f"Secret key is: {app.config['SECRET_KEY']}"

Notice the use of os.environ.get with a fallback value. This pattern prevents your app from crashing if the environment variable isn’t set, which is handy during development.

But this only scratches the surface. Flask also supports a built-in way to load configurations from environment variables by using the from_envvar method, which loads settings from a file whose path is specified in an environment variable. This might sound meta, but it is useful when you want to keep all your configuration in a single file outside your codebase.

Here’s how you might use it:

import os
from flask import Flask

app = Flask(__name__)
app.config.from_envvar('MYAPP_SETTINGS', silent=True)

In this case, you would set an environment variable MYAPP_SETTINGS pointing to a file containing key-value pairs, for example:

SECRET_KEY=supersecretkey
DATABASE_URL=postgresql://user:pass@localhost/dbname

However, this approach is less common nowadays compared to using third-party libraries like python-dotenv, which let you keep environment variables in a .env file during development and automatically load them into os.environ. Flask 2.0+ even integrates with python-dotenv out of the box.

One subtlety to watch out for is that environment variables are always strings. So if you need integers, booleans, or lists, you’ll need to convert them explicitly. For example:

DEBUG = os.environ.get('DEBUG', 'False').lower() in ('true', '1', 't')
PORT = int(os.environ.get('PORT', 5000))

This is important because a common mistake is to assume that os.environ.get('DEBUG') will return a boolean when it actually returns the string ‘False’, which evaluates to True in a boolean context.

Flask’s app.config is just a dictionary, so you can store these parsed values there and use them throughout your app. It’s a good practice to centralize this parsing logic in a configuration module or function so that your main app code doesn’t get cluttered.

One last thing: environment variables are process-wide. If you run multiple Flask apps or workers on the same machine, you have to be careful not to overwrite or leak values. Containers help isolate these environments, but on bare metal, sticking to convention and naming your variables carefully very important.

Understanding how environment variables interact with Flask’s configuration system lays the groundwork for more secure and flexible applications. It’s the difference between an app that just works on your laptop and one that can be deployed anywhere without code changes. The moment you stop hardcoding secrets and start relying on environment variables, you’ll notice a cleaner, more professional development workflow that scales.

Setting up .env files for configuration

The .env file is a simple text file where you declare environment variables, one per line, in the form KEY=VALUE. It’s not part of the Python or Flask ecosystem per se, but a convention popularized by tools like python-dotenv. This file should never be committed to source control if it contains secrets or environment-specific settings.

To set this up, first install the library:

pip install python-dotenv

Next, create a file named .env in your project root with contents like:

FLASK_ENV=development
SECRET_KEY=supersecretkey
DATABASE_URL=postgresql://user:pass@localhost/dbname
DEBUG=True
PORT=5000

With this file in place, you can load these variables automatically at app startup by adding the following near the top of your app.py or wherever your Flask app is created:

from dotenv import load_dotenv
import os

load_dotenv()  # This loads the .env file into os.environ

app = Flask(__name__)
app.config['SECRET_KEY'] = os.environ.get('SECRET_KEY')
app.config['DEBUG'] = os.environ.get('DEBUG', 'False').lower() in ('true', '1', 't')
app.config['SQLALCHEMY_DATABASE_URI'] = os.environ.get('DATABASE_URL')

This approach keeps your application code clean and separates configuration from code. The load_dotenv() function reads the .env file and adds its keys to os.environ, making them accessible just like real environment variables set in your shell.

One handy trick is to specify the path explicitly when your .env file doesn’t live in the root directory or if you want to load multiple files:

from dotenv import load_dotenv
from pathlib import Path

env_path = Path('.') / '.env'
load_dotenv(dotenv_path=env_path)

For production, you often won’t use a .env file at all. Instead, your deployment environment—like a container orchestration system, CI/CD pipeline, or cloud provider—will set environment variables directly. Still, using .env files locally speeds up development and testing.

Flask 2+ automatically loads .env files if you use the built-in Flask CLI, so running flask run in development will pick up environment variables without extra code. But if you run your app with python app.py, you’ll need to call load_dotenv() manually.

Remember that .env files do not support complex data types, multiline values, or comments in the middle of lines. Values are always strings, so you still need to parse and convert them in your code. For example, to handle a comma-separated list, you might write:

allowed_hosts = os.environ.get('ALLOWED_HOSTS', '')
ALLOWED_HOSTS = [host.strip() for host in allowed_hosts.split(',') if host]

In summary, .env files are a lightweight, human-readable method to manage environment variables during development. They keep secrets out of your codebase and let you switch configurations by editing a simple file rather than changing code. The line between .env and real environment variables is thin but important: one is a file for local convenience, the other is the actual environment your app runs in.

As your project grows, you might want to structure configuration loading into a dedicated module:

# config.py
import os
from dotenv import load_dotenv

load_dotenv()

class Config:
    SECRET_KEY = os.environ.get('SECRET_KEY')
    DEBUG = os.environ.get('DEBUG', 'False').lower() in ('true', '1', 't')
    SQLALCHEMY_DATABASE_URI = os.environ.get('DATABASE_URL')
    PORT = int(os.environ.get('PORT', 5000))
    ALLOWED_HOSTS = [h.strip() for h in os.environ.get('ALLOWED_HOSTS', '').split(',') if h]

# app.py
from flask import Flask
from config import Config

app = Flask(__name__)
app.config.from_object(Config)

This isolates environment parsing logic and makes your Flask app instantiation cleaner. It also makes it easier to add multiple configurations for different environments by subclassing Config and switching based on an environment variable.

Setting up .env files is a small step that pays off in cleaner, more maintainable Flask applications. But it’s just the beginning of managing configuration securely and effectively.

Best practices for managing secrets in Flask applications

Handling secrets in Flask applications demands more than just convenience; it requires deliberate care to prevent accidental exposure. The first rule is to never commit secrets like API keys, database passwords, or cryptographic keys into your version control system. Even if your repository is private, leaks happen—whether through forks, logs, or public pull requests.

One simpler strategy is to add your .env file to your .gitignore so it stays local. But that’s only the start. For production environments, rely on secure secret management systems provided by your infrastructure. Cloud providers like AWS, GCP, and Azure offer dedicated secret stores with encryption, access control, and audit logging.

If you’re deploying with Docker, use Docker secrets or environment variables passed securely via orchestration tools like Kubernetes. Here’s an example of referencing a secret in a Kubernetes manifest:

apiVersion: v1
kind: Pod
metadata:
  name: flask-app
spec:
  containers:
  - name: flask-container
    image: my-flask-image
    env:
      - name: SECRET_KEY
        valueFrom:
          secretKeyRef:
            name: flask-secrets
            key: secret_key

Within your Flask app, you access SECRET_KEY as usual from os.environ, but the secret itself never lives in your code or container images.

Another best practice is to rotate secrets periodically. This limits the damage if a secret is compromised. Automate rotation where possible, and design your app to reload configuration without downtime, for example by supporting a configuration reload endpoint or restarting gracefully.

Use environment variables only for configuration and secrets, never for storing application state or user data. They’re process-wide and visible to any subprocess or user with access to the environment, so treat them as sensitive but transient.

When it comes to the Flask SECRET_KEY, it should be a long, random string suitable for cryptographic use. Never use trivial or guessable values in production. You can generate one with Python:

import os
print(os.urandom(24).hex())

Store this securely and load it via environment variables rather than hardcoding. This key underpins session security and CSRF protection, so it’s a linchpin of your app’s trustworthiness.

Logging is another place where secrets can leak inadvertently. Avoid logging environment variables or configuration values that contain sensitive information. If you must log configuration for debugging, sanitize or mask secrets before output.

Lastly, consider limiting the scope of environment variables to only what your Flask app needs. Avoid bloating os.environ with unrelated secrets or credentials. This reduces the attack surface and makes auditing easier.

Here’s a concise example of a secure configuration loading pattern:

import os
from flask import Flask

def get_secret(key, default=None):
    value = os.environ.get(key, default)
    if value is None:
        raise RuntimeError(f"Missing required secret: {key}")
    return value

app = Flask(__name__)
app.config['SECRET_KEY'] = get_secret('SECRET_KEY')
app.config['DATABASE_URL'] = get_secret('DATABASE_URL')
app.config['DEBUG'] = os.environ.get('DEBUG', 'False').lower() in ('true', '1', 't')

This forces your app to fail fast if critical secrets aren’t set, which is preferable to silently running with insecure defaults.

Managing secrets well is a discipline. It’s about clear separation between code and config, secure storage, controlled access, and auditing. Flask gives you the flexibility to integrate with whatever secret management tools fit your deployment environment, but the responsibility to keep secrets safe always rests with the developer.