Cómo usar variables de entorno con python-dotenv en Python

Guardar contraseñas, claves de API o cadenas de conexión directamente en el código es uno de los errores más comunes — y más peligrosos — en los proyectos de datos. Las variables de entorno resuelven el problema: mantienen la configuración fuera del código, evitan exponer secretos y facilitan usar valores distintos en tu portátil y en el servidor. En Python, la forma más sencilla de trabajar con variables de entorno es la biblioteca python-dotenv y un archivo .env.

Requisitos previos

• Python 3.8 o superior (compruébalo con python --version).
• Un editor de código, como Visual Studio Code.
• Saber usar la terminal para instalar paquetes con pip.
• Preferiblemente, un entorno virtual creado para el proyecto.

Paso 1: Instalar python-dotenv

La biblioteca python-dotenv lee archivos .env y pone esos valores a disposición de tu programa. Es ligera, no tiene dependencias externas y se instala con un solo comando en la terminal:

pip install python-dotenv

Si trabajas dentro de un entorno virtual, actívalo antes de instalar para mantener el paquete aislado del resto del sistema.

Paso 2: Crear el archivo .env

En la raíz del proyecto, crea un archivo llamado .env — solo el punto seguido del nombre, sin ninguna extensión. Dentro, escribe una variable por línea, con el formato NOMBRE=valor, sin espacios alrededor del signo igual:

DB_HOST=localhost
DB_USER=analytics
DB_PASSWORD=super-secreta-123
API_KEY=sk-exemplo-abcdef

Por convención, los nombres se escriben en mayúsculas. No hacen falta comillas: todo lo que está a la derecha del signo igual se interpreta como texto.

Paso 3: Proteger el archivo .env

Un secreto solo está seguro si nunca sale de tu ordenador. Si usas Git, añade .env a tu archivo .gitignore para asegurarte de que nunca se envíe al repositorio:

echo ".env" >> .gitignore

También es buena práctica crear un archivo .env.example con los nombres de las variables pero sin los valores reales. Así, quien clone el proyecto sabe exactamente qué configuración debe rellenar.

Paso 4: Cargar las variables en Python

Con el archivo listo, llega la parte del código. La función load_dotenv() busca un archivo .env en la carpeta actual y coloca cada valor en el entorno del proceso. A partir de ahí, os.getenv() devuelve el valor de cada variable por su nombre:

import os
from dotenv import load_dotenv

load_dotenv()

db_host = os.getenv("DB_HOST")
db_user = os.getenv("DB_USER")
api_key = os.getenv("API_KEY")

print(db_host, db_user)

Fíjate en que no hay ni una sola contraseña escrita en el código: todos los valores sensibles viven en el archivo .env. Un detalle importante: por defecto, load_dotenv() no sustituye las variables que ya están definidas en el sistema. Es intencionado, para que la configuración del servidor tenga siempre prioridad sobre el archivo local.

Paso 5: Valores por defecto y evitar errores

Cuando una variable no existe, os.getenv() devuelve None, lo que suele provocar un error más adelante en el programa. Para evitarlo, indica un valor por defecto como segundo argumento:

port = os.getenv("DB_PORT", "5432")

Si la variable es obligatoria, lo mejor es validarla al arrancar y fallar con un mensaje claro, en lugar de dejar que el error aparezca más tarde:

api_key = os.getenv("API_KEY")
if not api_key:
    raise RuntimeError("API_KEY not found")

Comprobar el resultado

Guarda el código en un archivo, por ejemplo config_teste.py, y ejecútalo en la terminal:

python config_teste.py

Si ves impresos el host y el usuario correctos, la lectura funcionó. También puedes confirmar que el archivo se encontró realmente, porque load_dotenv() devuelve True cuando carga un .env con éxito y False en caso contrario. Si las variables llegan como None, el problema más común es que el archivo .env no esté en la misma carpeta desde la que ejecutas el script — corrige la ruta o pasa la ubicación exacta a load_dotenv().

Conclusión

En cinco pasos separaste la configuración del código y dejaste de tener secretos escritos en tus scripts — una base esencial para proyectos de datos seguros y fáciles de mover entre entornos. El siguiente paso es usar estas variables en una conexión real, como a una base de datos SQL Server o a una API. ¿Cuál será el primer secreto que sacas de tu código: la contraseña de la base de datos o la clave de API?