Servidor HTTP simple en Python: guía práctica

Python incluye un servidor HTTP sencillo que permite compartir archivos, probar páginas HTML y levantar un entorno local en pocos segundos. Es una herramienta práctica para desarrollo, demostraciones y tareas dentro de una red confiable. No reemplaza a Nginx, Apache ni a un servidor de producción, pero resulta excelente para pruebas rápidas.

Crear un servidor HTTP en segundos

Abre el terminal en la carpeta que quieres compartir y ejecuta:

python -m http.server

Por defecto, Python utiliza el puerto 8000. Después abre http://localhost:8000 en el navegador. Verás un índice de archivos o la página index.html si existe. Para comenzar desde una base más amplia, consulta esta ruta para aprender programación desde cero.

Cambiar el puerto y la carpeta

El puerto puede indicarse como argumento:

python -m http.server 8080

También puedes servir una carpeta sin cambiar el directorio actual:

python -m http.server 8000 --directory ./sitio

Si el puerto está ocupado, el comando mostrará un error. Elige otro número, por ejemplo 8080 o 9000. En algunos sistemas, los puertos inferiores a 1024 requieren permisos elevados y no son recomendables para pruebas normales.

Acceso desde otro dispositivo de la red

Para probar una página desde un teléfono o una segunda computadora, identifica la dirección IP local del equipo que ejecuta el servidor. Después visita una URL como http://192.168.1.20:8000. Ambos dispositivos deben estar en la misma red y el firewall debe permitir la conexión.

Este método es útil para revisar diseños responsivos o transferir archivos temporalmente, pero debes utilizarlo solo en redes confiables. El módulo expone el contenido de la carpeta, por lo que no conviene ejecutarlo en directorios con documentos privados.

Cómo funciona el módulo http.server

El comando utiliza el módulo http.server de la biblioteca estándar. Su documentación oficial explica las clases disponibles y advierte que no está recomendado para producción. Internamente, el servidor recibe solicitudes HTTP y responde con archivos o listados de directorio.

Para comprender cómo se organizan operaciones reutilizables, revisa la guía de funciones en Python. El servidor también se apoya en la infraestructura de socketserver, que proporciona clases para manejar conexiones de red.

Crear un manejador personalizado

Cuando necesitas controlar una respuesta, puedes crear un script con BaseHTTPRequestHandler:

from http.server import BaseHTTPRequestHandler, HTTPServer

class Manejador(BaseHTTPRequestHandler):
    def do_GET(self):
        contenido = b"Hola desde Python"
        self.send_response(200)
        self.send_header("Content-Type", "text/plain; charset=utf-8")
        self.send_header("Content-Length", str(len(contenido)))
        self.end_headers()
        self.wfile.write(contenido)

servidor = HTTPServer(("127.0.0.1", 8000), Manejador)
print("Servidor activo en http://127.0.0.1:8000")
servidor.serve_forever()

Este ejemplo devuelve texto para cualquier ruta. Se puede ampliar para detectar self.path, responder JSON o servir archivos concretos. Sin embargo, cuando el proyecto necesita rutas, validación y documentación, es mejor utilizar FastAPI o un framework equivalente.

Servir solo en localhost o en todas las interfaces

La dirección de enlace define quién puede conectarse. 127.0.0.1 limita el acceso a la misma computadora. 0.0.0.0 escucha en todas las interfaces disponibles. Para pruebas personales, localhost es la opción más segura. Solo usa todas las interfaces cuando realmente necesites acceso desde la red local.

Problemas frecuentes

Si el navegador no conecta, comprueba que el proceso sigue activo, que el puerto coincide y que el firewall no bloquea Python. Si aparece una página antigua, limpia la caché o abre una ventana privada. Si los caracteres se muestran mal, verifica el encabezado de codificación y guarda los archivos en UTF-8.

Otro error común es iniciar el servidor desde la carpeta equivocada. El módulo publica el directorio actual, así que ejecuta pwd en macOS o Linux, o cd en Windows, para verificar la ruta. También puedes usar --directory para evitar confusiones.

Cuándo no utilizarlo

No uses http.server para alojar un sitio público, procesar contraseñas, recibir pagos ni manejar archivos sensibles. No incluye las protecciones, el rendimiento ni la configuración de un servidor profesional. Para una aplicación completa puedes estudiar Django; para una API, FastAPI; y para archivos estáticos en producción, un servidor como Nginx o un servicio especializado.

Ideas prácticas

El servidor simple es útil para probar una landing page, revisar archivos generados por un script, compartir un informe en una red local o simular un origen HTTP durante el desarrollo. También puede integrarse en pequeños scripts, aunque debes controlar bien cuándo se inicia y se detiene.

Si el proyecto necesita configuración, evita guardar datos sensibles en el código y aplica las recomendaciones de variables de entorno en Python. Utilizado con límites claros, http.server es una de las herramientas más rápidas y útiles de la biblioteca estándar.

Registrar solicitudes y detener el servidor

El manejador predeterminado escribe en el terminal la dirección del cliente, la ruta y el código de respuesta. Esta salida ayuda a comprobar si el navegador realmente realizó la solicitud. En un manejador personalizado puedes sobrescribir log_message, aunque no conviene eliminar todos los registros durante la depuración. Para detener el comando ejecutado en el terminal, utiliza Ctrl+C. En un script, el cierre debe realizarse de forma ordenada para liberar el puerto.

Tipos MIME y archivos estáticos

El navegador interpreta cada archivo según su tipo MIME. El servidor sencillo reconoce extensiones comunes como HTML, CSS, JavaScript, PNG y JPEG. Si un archivo se descarga en vez de mostrarse, o si un módulo JavaScript es bloqueado, revisa la extensión y la cabecera Content-Type. También recuerda que abrir un archivo HTML directamente con file:// no siempre se comporta igual que servirlo mediante HTTP; algunas funciones del navegador exigen un origen HTTP.

Un servidor de desarrollo no es una aplicación web

Servir archivos estáticos no proporciona formularios procesados, usuarios, sesiones ni persistencia. Para recibir datos y aplicar reglas necesitas una aplicación. El servidor simple es una pieza de aprendizaje y prueba, no una arquitectura completa. Esta distinción evita intentar añadir manualmente autenticación, rutas y seguridad a una herramienta que no fue diseñada para ese propósito.