Crear variables de entorno en Flask .flaskenv

▶

Aprendido cómo crear un sistema de rutas CRUD en Flask, otro factor importantes es como configurar variables de entorno en Flask puede parecer algo opcional, pero en realidad es una pieza clave para que tu aplicación funcione correctamente, sobre todo cuando usas herramientas como Flask Migrate, la Shell interactiva o el comando flask run.
En mi caso, fue al integrar Flask Migrate cuando entendí la importancia de tener bien definidas las variables del entorno. Sin ellas, Flask ni siquiera sabía qué aplicación debía ejecutar.

Desde la terminal (Windows, Linux y macOS)

Antes de usar archivos, podías establecerlas así:

# En Linux / macOS
export FLASK_APP=my_app
# En Windows
set FLASK_APP=my_app

Qué son las variables de entorno y por qué importan en Flask

Las variables de entorno son valores externos al código que definen el comportamiento de una aplicación. En Flask se usan, por ejemplo, para indicar qué aplicación debe iniciarse, el modo de ejecución o el puerto del servidor.

Qué papel cumplen en el desarrollo y la seguridad

Su función es separar la configuración sensible del código fuente. Así evitas dejar expuestas claves o tokens (por ejemplo, SECRET_KEY o API_KEY) en los archivos del proyecto.

Diferencia entre variables globales y de aplicación

Las globales afectan al sistema operativo (por ejemplo, PATH), mientras que las de aplicación controlan el comportamiento de Flask (FLASK_APP, FLASK_ENV, FLASK_DEBUG, etc.).
Gracias a esto puedes mantener distintos entornos: desarrollo, pruebas y producción, sin modificar tu código base.

Archivos .env y .flaskenv: la forma moderna de configurar Flask

Cuando comencé a trabajar con Flask, tenía que establecer las variables manualmente cada vez que abría una terminal. Luego descubrí que Flask permite gestionarlas desde archivos.

Esto facilita muchísimo el flujo de trabajo, ya que basta con crear dos archivos en la raíz del proyecto: .env y .flaskenv.

Qué diferencia hay entre .env y .flaskenv
Archivo    Propósito    Ejemplo
.flaskenv    Configuración para comandos de Flask CLI    FLASK_APP=my_app
.env    Configuración general de la aplicación

Hemos visto cómo establecerla mediante la terminal como mostramos en el capítulo 5, en la cual era requerida para poder ejecutar los comandos de Flask Migrate. Pero no hemos visto todo el potencial que esto nos ofrece y cómo lo usa Flask. Por ejemplo, podemos emplear archivos para manejar estas variables de entorno, al igual que ocurre con tecnologías como CodeIgniter o Laravel, podemos crear estos archivos para manejar las variables de entorno del proyecto:

Dónde se crean y cómo los detecta Flask

Ambos se colocan en la carpeta raíz del proyecto. Flask los detecta automáticamente si tienes instalado el paquete python-dotenv.

Ejemplo práctico de estructura de proyecto
my_app/
│
├── __init__.py
├── config.py
├── .env
├── .flaskenv
└── run.py

.env

Y en el caso de Flask, también el:

.envflask 

Para manejar estas variables de entorno.

En este capítulo vamos a conocer cómo emplear las variables de entorno mediante archivos.

Vamos a crear una nueva aplicación como hablamos en el capítulo 1.

Si intentamos ejecutar:

$ flask run

Veremos un error como el siguiente:

Error: Could not locate a Flask application. You did not provide the "FLASK_APP" environment variable, and a "wsgi.py" or "app.py" module was not found in the current directory.

En el cual nos indica que se debe de establecer la variable de entorno llamada FLASK_APP indicando el nombre del módulo de la aplicación en Flask.

Para ello, podemos hacerlo mediante la terminal, en Mac o Linux:

$ export FLASK_APP=my_app

En Windows:

$ set FLASK_APP=my_app

O establecerlo en el archivo:

.flaskenv

FLASK_APP=my_app

El valor de FLASK_APP corresponde al nombre del módulo, que en este ejemplo se llama como my_app:

my_app/__init__.py

config.py

.env

.flaskenv

run.py

En donde se encuentra el archivo de arranque de la aplicación:

my_app/__init__.py

Ahora, si intentamos ejecutar el comando de:

$ flask run

Veremos que aun no funciona, sito se debe a que Flask no esta reconociendo el archivo generado anteriormente; para que lo reconozca como una entrada válida para establecer las variables de entorno, debemos de instalar un paquete adicional:

$ pip install python-dotenv

Si ejecutamos nuevamente:

$ flask run

Veremos que ahora si el servidor inicia correctamente; si intentamos ejecutar otros comandos que requieren de conocer la instancia de la aplicación, la variable llamada app que se encuentra dentro de my_app/__init__.py.

La ventaja fundamental de emplear los archivos para manejar las variables de entorno es que no debemos de establecer cada vez que abrimos una terminal las variables de entorno de nuestra aplicación, ya que son tomados desde el archivo.

Estas son las opciones principales que podemos configurar:

• FLASK_ENV - Indica el ambiente, por defecto es production.
• FLASK_DEBUG - Indica si la aplicación está en modo DEBUG, por defecto es TRUE.
• FLASK_APP - Se utiliza para especificar el módulo de la aplicación.
• FLASK_RUN_PORT - Para especificar el puerto al momento de iniciar la aplicación.

Puedes conocer otras variables de entorno de Flask en:

https://flask.palletsprojects.com/en/latest/config/

Tenemos dos archivos de puntos: .env y .flaskenv. Usamos .flaskenv para cualquier comando de configuración de Flask CLI y usar .env para la configuración de nuestra aplicación.

Por ejemplo, especificamos el nombre del módulo, como hicimos anteriormente:

.flaskenv

FLASK_APP=my_app

Y en este archivo cualquier otra configuración que no tenga el prefijo de FLASK_*:

.env

SECRET_KEY=12345
API_KEY=123

Podemos especificar otras configuraciones como:

.flaskenv

FLASK_ENV=development
FLASK_RUN_PORT=8080

Para acceder a las variables de entorno desde el proyecto, debemos de emplear la función de environ():

config.py

from os import environ 
SECRET_KEY = environ.get('SECRET_KEY')
API_KEY = environ.get('API_KEY')
FLASK_APP = environ.get('FLASK_APP')

La ventaja principal de emplear los archivos para manejar la variables de entorno es que podemos tener en un solo lugar todas las variables de entorno del proyecto, podemos tener múltiples configuraciones en otros archivos tipo .env y cambiar de uno a otro fácilmente y tener archivos para manejar las variables de entorno para desarrollo, producción, pruebas, entre otros.

Buenas prácticas y entornos múltiples (dev, test, prod)

En proyectos reales suelo tener varios archivos .env: uno para desarrollo, otro para producción y otro para pruebas.
Esto evita mezclar configuraciones y facilita el despliegue continuo.

Separar configuraciones sin complicarse

Crea copias del archivo .env:

.env.development
.env.production
.env.test

Y cambia entre ellos según el entorno que necesites.

Ejemplo de uso con múltiples archivos .env

Puedes escribir un pequeño script para cargar el archivo adecuado antes de arrancar Flask.

Consejos para mantener la seguridad

• No subas los archivos .env a tu repositorio (usa .gitignore).
• Evita incluir claves sensibles en texto plano.

❌ Errores comunes y cómo resolverlos

“Could not locate a Flask application…”

Ocurre cuando FLASK_APP no apunta al módulo correcto. Revisa el nombre del archivo o el contenido de .flaskenv.

Variables no reconocidas o duplicadas

Asegúrate de que python-dotenv esté instalado y que no tengas espacios ni comillas innecesarias en los archivos .env.

Cuándo Flask ignora el archivo .flaskenv

Si ejecutas tu aplicación desde un entorno virtual o servidor externo sin python-dotenv, Flask no leerá automáticamente los archivos de entorno. Cárgalos manualmente en __init__.py.

En Flask tenemos múltiples variables de entorno que podemos emplear para realizar distintas configuraciones, activar modo debug, especificar archivo de arranque o principal de la aplicación entre otras muchas configuraciones que podemos realizar.

En esta entrada vamos a ver algunas de las variables de entorno principales que podemos emplear en Flask.

Variables de entorno principales que podemos emplear en Flask

En Flask tenemos múltiples variables de entorno que podemos emplear para realizar distintas configuraciones, activar modo debug, especificar archivo de arranque o principal de la aplicación entre otras muchas configuraciones que podemos realizar.

En esta entrada vamos a ver algunas de las variables de entorno principales que podemos emplear en Flask.

Variable de entorno: FLASK_APP

Esta viene siendo si no es la más importante, una de las más importantes que debemos conocer; con esto estamos indicando cual es el archivo de arranque de nuestro proyecto en Flask; su uso es muy sencillo:

Ejemplo de su uso: (Linux y MacOS)

export FLASK_APP=run.py

Con esta configuración podemos indicar el archivo de arranque de nuestra aplicación. Así que cuando vayamos a ejecutar la app con

Flask run

Flask va a tomar la configuración del nombre que configuramos anteriormente para ejecutar la app

También podemos ejecutar otros tipos de configuraciones por ejemplo, cuando ejecutamos una migración con Flask Migrate, como tratamos en el curso de:

Y bueno, hay muchos procesos o paquetes que puedes instalar en los cuales debes de especificar el FLASK_APP antes de iniciar dicho proceso, ya que con esto, estamos indicando donde se empiezan a cargar todas las dependencias y nuestro proyecto como tal.

Variable de entorno: FLASK_DEBUG

Con esta configuración podemos habilitar o deshabilitar el modo debut en nuestra aplicación que nos sirve por ejemplo para mostrar información detallada sobre un error que está ocurriendo en nuestra app y también es empleada por otros paquetes por ejemplo el de Flask Google Captcha para habilitar el uso del captcha o deshabilitar el mismo.

Ejemplo de su uso: (Linux y MacOS)

export FLASK_DEBUG=1

Variable de entorno: FLASK_ENV

Con esta podemos configurar el ambiente de nuestra aplicación

Ejemplo de su uso: (Windows)

set FLASK_ENV=development

Puedes ver la lista completa de variables de entorno de Flask en Variables entorno

Conclusión

Usar variables de entorno correctamente marca la diferencia entre un proyecto amateur y uno profesional, de esta forma, podemos reutilizar fácilmente piezas claves de código al configurar .env y .flaskenv me ahorró tiempo, errores y me permitió automatizar despliegues sin tocar el código.

❓ Preguntas frecuentes

¿Por qué usar .flaskenv si ya tengo .env?
Porque .flaskenv se lee antes y permite que Flask CLI conozca el módulo y entorno sin ejecutarse manualmente.

¿Qué pasa si no instalo python-dotenv?
Flask no cargará automáticamente los archivos .env ni .flaskenv, y tendrás que exportar las variables cada vez.

¿Puedo definir variables distintas según el entorno?
Sí, puedes tener múltiples archivos .env (por ejemplo, .env.dev, .env.prod) y cargarlos según la fase del proyecto.

El siguiente paso es el de aprender a trabajar con Jinja2 para el manejo de los templates