# python-magic: la forma más práctica de confiar en el contenido del archivo en lugar de la extensión

Cuando se añade una función de carga de imágenes a un servidor, pronto surgen estas necesidades.

* “Sube como `.png`, pero ¿es realmente PNG?”
* “Primero hay que decidir si el archivo es una imagen o un documento.”
* “Antes de usar un parser externo (Pillow/OpenCV), quiero comprobar al menos el tipo.”

El punto de partida más sólido es el **contenido** del archivo, no la extensión.
Y la herramienta más sencilla para obtener esa “determinación basada en el contenido” es `python-magic`.

---

## ¿Qué hace python-magic? {#sec-a08d76193220}

`python-magic` es un *wrapper* que permite usar la librería C `libmagic` desde Python. `libmagic` inspecciona características como el **cabezal** (los primeros bytes) de un archivo para identificar su tipo. Esta funcionalidad también está disponible en el comando Unix `file`.

En resumen:

* `file` (comando Linux) = “interfaz de terminal”
* `libmagic` = “motor central (lógica de detección)”
* `python-magic` = “wrapper ligero que llama a libmagic desde Python”

Este artículo se centra en `python-magic` y explica de forma estructurada cómo el motor determina el tipo de archivo.

---

## ¿Cómo funciona el motor central (libmagic)? {#sec-3ca38aa1c6cf}

![Diagrama de funcionamiento de la librería libmagic](/media/editor_temp/6/0d5baf67-d72a-4f8d-9f1b-e273eaaba587.png)

La esencia de libmagic es simple.

> “Lee una base de datos de reglas de detección de tipos de archivo, inspecciona los bytes del archivo según esas reglas y llega a la conclusión más probable.”

La base de datos es el *magic database* (BD de patrones mágicos) que se instala junto con `file`/libmagic, normalmente en forma compilada (`magic.mgc`).

### 1) El “archivo mágico” es un conjunto de reglas {#sec-0d6d47a4ad53}

Estas reglas se componen de:

* **Dónde mirar** (offset: posición de bytes en el archivo)
* **Cómo leer** (tipo: byte/cadena/entero, etc.)
* **Con qué comparar** (valor/patrón esperado)
* **Qué conclusión sacar** (mensaje/MIME, etc.)

El manual de `file` describe que inspecciona *magic patterns*. Cada línea se prueba (offset/tipo/valor/mensaje) y, si coincide, se avanza a pruebas más específicas en una estructura jerárquica.

Para profundizar en el comando `file` de Linux, haz clic en el siguiente enlace:

[Explorar el comando file de Linux](https://cmdbox.mikihands.com/file/)

### 2) La BD de reglas tiene una versión “texto” y una “compilada” {#sec-3692748a59f7}

El BD puede ser un conjunto de fragmentos de texto legibles por humanos, pero por rendimiento suele entregarse también en formato binario compilado (`.mgc`).

### 3) En última instancia, lo que hace es “mirar el contenido en lugar de la extensión” {#sec-9d312e1d9ed0}

`file` sigue la filosofía de detectar tipos mirando el contenido, no la extensión. `python-magic` trae esa filosofía a Python con una sola línea de código.

---

## ¿Cómo usar python-magic? {#sec-d0f1c4230032}

Hay dos patrones de uso comunes.

### 1) Obtener el tipo MIME (el más práctico) {#sec-ffe8c3253960}

Útil para procesamiento de carga, enrutamiento y métricas.

```python
import magic

mime = magic.from_file("upload.bin", mime=True)
print(mime)  # Ejemplo: image/png
```

`python-magic` identifica el tipo de archivo basado en libmagic, tal como lo hace el comando `file`.

### 2) Detectar directamente a partir de bytes (útil para flujos de carga) {#sec-030160959863}

A menudo se quiere inspeccionar solo los primeros bytes antes de escribir el archivo en disco.

```python
import magic

with open("upload.bin", "rb") as f:
    head = f.read(4096)

mime = magic.from_buffer(head, mime=True)
print(mime)
```

(La detección basada en buffer es especialmente buena como filtro de primera pasada antes de almacenar el archivo.)

---

## ¿Dónde resulta útil desde la perspectiva del desarrollador? {#sec-78dbbfda0e18}

### 1) Primera línea de defensa en la validación de carga {#sec-ea23ba6ff650}

* No depender solo de la extensión
* Confirmar mínimamente si el archivo puede ser tratado como imagen

### 2) Punto de bifurcación en la tubería de procesamiento {#sec-ef95b692a826}

* Si es imagen → pipeline de redimensionado/thumbnail
* Si es PDF/ZIP → otro worker
* Si el tipo es desconocido → aislar/rechazar/validación adicional

### 3) Reducir costos antes de llamar a “decoders pesados” {#sec-508e3c95c8ee}

Decoders como Pillow son potentes pero costosos en memoria/CPU y aumentan la superficie de vulnerabilidad. `python-magic` ayuda a decidir si vale la pena invocar ese decoder.

> Nota importante: libmagic es solo una herramienta de *estimación/detección*. Si la seguridad completa (bloqueo de cargas maliciosas) es el objetivo, se requieren validaciones adicionales (lista blanca, límite de tamaño, decodificación en sandbox, etc.).

---

## Conclusión: python-magic es la forma más ligera de traer la detección de tipos de archivo al código {#sec-3b1611aa0fb2}

`python-magic` no procesa imágenes; simplemente indica rápidamente cómo debe tratarse el archivo.

* Motor: libmagic (igual que `file`)
* Método de detección: “BD de reglas + inspección de bytes”
* En la práctica: útil para validación de carga, enrutamiento y ahorro de recursos

Conocerlo permite construir un flujo de “detección → bifurcación → protección” incluso en entornos con bibliotecas limitadas.

---

## Próximo artículo {#sec-832d5436b8b1}

* Analizaremos qué garantizan los métodos `open()`, `load()` y `verify()` de Pillow (PIL), cuándo usar cada uno y cómo funcionan internamente.

---

**Ver artículos relacionados**  

- [La visión del desarrollador sobre la estructura de un archivo de imagen](/ko/whitedec/2026/1/14/developer-view-image-file-common-structure/)