127.0.0.1:5000 en Flask: qué es y cómo solucionar errores

Ejecutas python app.py por primera vez y en la terminal aparece esto:

 * Running on http://127.0.0.1:5000
 * Debug mode: on

Abres el navegador, pegas esa dirección y funciona. Tu web está ahí. Pero si alguien te pregunta qué acabas de hacer, o por qué esa URL concretamente, no tienes muy claro qué responder.

Vamos por partes. Y si todavía no tienes el entorno preparado, primero mira cómo configurar VS Code desde cero — es el editor que usarás para todo esto.

Qué es 127.0.0.1

Cada dispositivo conectado a una red tiene una dirección IP. La tuya en internet puede ser algo como 88.12.45.200. La de tu router en la red local, algo como 192.168.1.1.

Pero 127.0.0.1 es especial: es la dirección que un ordenador usa para referirse a sí mismo. Da igual el sistema operativo, da igual si tienes conexión a internet o no. El rango 127.x.x.x está reservado para esto en el estándar de redes (RFC 5735), y 127.0.0.1 es la dirección de loopback por defecto.

Cuando Flask escucha en 127.0.0.1, está diciendo: "acepto peticiones que vengan de este mismo ordenador". No de la red, no de internet. Solo de ti.

Por eso también funciona si escribes localhost en lugar de 127.0.0.1: en casi todos los sistemas, localhost es simplemente un alias para esa dirección. Tu ordenador lo resuelve igual.

Qué es el puerto 5000

Una dirección IP identifica el ordenador. El puerto identifica a qué programa dentro de ese ordenador va la petición.

Imagínalo como un edificio: la IP es la dirección del edificio, el puerto es el número de apartamento. Cuando escribes 127.0.0.1:5000, le estás diciendo al navegador: "ve a este ordenador, y dentro de él, llama al programa que está escuchando en el puerto 5000".

Flask usa el 5000 por convención, pero no hay nada mágico en ese número. Si quieres cambiar el puerto, puedes hacerlo directamente al arrancar la aplicación:

from flask import Flask

app = Flask(__name__)

if __name__ == '__main__':
    app.run(port=8080)  # ahora escucha en http://127.0.0.1:8080

Algunos puertos están reservados por el sistema (80 para HTTP, 443 para HTTPS, 22 para SSH). Para desarrollo local suelen usarse puertos altos como el 5000, 8000 u 8080 porque no requieren permisos especiales.

Por qué solo tú puedes verlo

Aquí es donde la mayoría se lleva la primera sorpresa: le dices a alguien "oye, entra a mi web" y le mandas la URL http://127.0.0.1:5000. No le funciona. Lo que está pasando es exactamente lo que explicamos antes: esa dirección es tu propio ordenador, no el suyo. Cuando él escribe 127.0.0.1, su sistema busca en su máquina, donde no hay ningún Flask corriendo.

Para que otra persona en tu misma red pueda acceder, necesitas que Flask escuche en 0.0.0.0 en lugar de 127.0.0.1. Eso le indica a Flask que acepte peticiones de cualquier interfaz de red, no solo de localhost:

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)

Con esto, alguien en tu misma WiFi puede entrar usando tu IP local (algo como 192.168.1.45:5000). Para saber tu IP local en Windows ejecuta ipconfig en la terminal; en Mac o Linux, ifconfig o ip addr.

Errores que te vas a encontrar

Esta sección es la que más gente busca después de ver esa URL por primera vez. Aquí están los más comunes y cómo solucionarlos.

Puerto ya en uso: Address already in use

El error completo suele ser:

OSError: [Errno 98] Address already in use

OSError: [WinError 10048] Only one usage of each socket address is normally permitted

Pasa cuando intentas arrancar Flask y el puerto 5000 ya lo está usando otro proceso. Casi siempre es otra instancia de Flask que no cerraste bien (Ctrl+C a veces no es suficiente si hay procesos colgados), o algún otro programa que coincide en el mismo puerto.

En Mac/Linux, para ver qué proceso ocupa el puerto y matarlo:

# Ver qué proceso usa el puerto 5000
lsof -i :5000

# Matar ese proceso (sustituye PID por el número que te devuelva lsof)
kill -9 PID

En Windows:

netstat -ano | findstr :5000
taskkill /PID numero_del_pid /F

La opción más rápida si no quieres liarte: cambia el puerto en app.run(port=5001) y listo.

Connection refused al abrir el navegador

Ves esto en el navegador:

This site can't be reached
127.0.0.1 refused to connect.

Casi siempre significa una de dos cosas: o Flask no está arrancado (la terminal donde lo ejecutaste se cerró, o el proceso terminó con algún error), o estás escribiendo un puerto diferente al que Flask está escuchando. Revisa la terminal: el mensaje Running on http://127.0.0.1:5000 tiene que estar ahí. Si no está, Flask no está corriendo.

Flask arranca pero el navegador no carga nada

Diferente al caso anterior: la página carga pero sale en blanco, o con un error 404. Lo primero que hay que mirar es la ruta. Si tu código tiene:

@app.route('/hola')
def hola():
    return 'Hola'

Tienes que entrar a http://127.0.0.1:5000/hola, no a http://127.0.0.1:5000. La raíz / solo funciona si tienes una ruta definida exactamente para /.

Funciona en local pero no en producción

Este ya no es un error de 127.0.0.1 propiamente dicho, pero aparece en el mismo momento de aprendizaje. Cuando subes tu app a un servidor real (Heroku, Railway, un VPS...), Flask ya no puede escuchar en 127.0.0.1 ni usar el servidor de desarrollo. El servidor de desarrollo de Flask no está pensado para producción: es de un solo hilo, sin gestión de errores robusta, y el modo debug expone datos internos.

En producción usarás Gunicorn o uWSGI delante de Flask. Pero eso es otra historia para cuando hayas salido de local.