Generar PDF en Django con WeasyPrint: HTML a PDF paso a paso

- Andrés Cruz - EN In english

Video thumbnail

Generar un PDF a partir de una plantilla HTML en Django es una necesidad muy común en cualquier proyecto que deba exportar reportes, facturas o certificados de forma dinámica. En esta guía te mostraré cómo hacerlo paso a paso usando WeasyPrint, una librería potente, multiplataforma y muy bien documentada que convierte directamente HTML y CSS en PDF sin depender de herramientas externas como wkhtmltopdf o Puppeteer.

Si vienes de leer sobre cómo escribir archivos CSV en Django, este es el siguiente paso natural: pasar de exportaciones planas a documentos con formato y diseño profesional.

¿Por qué generar un PDF en Django con WeasyPrint?

Convertir una página HTML a PDF directamente desde Django te permite presentar información de manera profesional y exportable sin salir de tu aplicación web. La ventaja clave frente a otras soluciones es que puedes aprovechar el sistema de plantillas de Django —con toda su lógica de contexto, variables y filtros— para construir el documento que quieras y luego convertirlo a PDF con unas pocas líneas de código.

Casos de uso comunes

  • Facturas y presupuestos automáticos.
  • Reportes de usuarios, ventas o métricas de negocio.
  • Certificados y comprobantes descargables.
  • Exportación de contenido dinámico como formularios, listados o contratos.

Ventajas de convertir plantillas HTML a PDF

  • Puedes reutilizar tus plantillas existentes de Django sin reescribir nada.
  • Mantienes control total sobre el diseño mediante CSS, incluyendo reglas de impresión con @page y @media print.
  • Los PDFs generados son compatibles con cualquier navegador o sistema operativo.
  • Soporte real de CSS3, a diferencia de alternativas como xhtml2pdf que solo entienden CSS2.

Instalación de WeasyPrint y dependencias según tu sistema operativo

WeasyPrint es un motor de renderizado que convierte HTML y CSS en PDF siguiendo los estándares de CSS Paged Media. Su instalación varía ligeramente según el sistema operativo, ya que requiere algunas librerías externas del sistema (principalmente Pango, Cairo y libffi) para poder procesar fuentes y diseño de página.

Instalación en Windows

En Windows, WeasyPrint necesita el entorno GTK+ para funcionar. Debes instalar el siguiente programa antes de instalar el paquete con pip:

GTK for Windows Runtime Environment Installer (GitHub)

Una vez instalado, asegúrate de que el directorio bin de GTK esté agregado correctamente al PATH del sistema; de lo contrario, WeasyPrint no podrá encontrar las librerías necesarias.

Instalación en macOS y Linux

En macOS puedes instalar las dependencias fácilmente con Homebrew:

$ brew install python pango libffi

En distribuciones Linux basadas en Debian/Ubuntu:

$ sudo apt-get install python3-pip libpango-1.0-0 libpangoft2-1.0-0

Puedes consultar las instrucciones detalladas para tu sistema en la documentación oficial de WeasyPrint.

Instalar WeasyPrint con pip

Una vez instaladas las dependencias del sistema, ya puedes instalar el paquete como una dependencia más de tu proyecto Python:

$ pip install weasyprint

Si usas un archivo de dependencias, recuerda añadirlo a tu requirements.txt:

$ pip freeze > requirements.txt

Crear una vista para generar un PDF en Django

Con las dependencias listas, vamos a crear una vista que convierta una plantilla HTML en un PDF descargable. La lógica central gira en torno a dos elementos de WeasyPrint: la clase HTML(), que acepta una URL o un string HTML, y el método write_pdf(), que escribe el resultado en un archivo o en un objeto de respuesta HTTP.

Ejemplo básico: convertir una URL a PDF

El uso más directo es indicar la URL que quieres convertir a PDF. En este ejemplo, útil como prueba de funcionamiento, convertimos la web de Google:

pdfs/views.py

from weasyprint import HTML

def generate_pdf(request):
    filename = "documents/archivo.pdf"
    HTML("https://www.google.com/").write_pdf(filename)
    return render(request, 'csv.html')

Esto generará un archivo archivo.pdf dentro del directorio documents/ del proyecto con el contenido de la URL especificada renderizado como PDF.

Generar un PDF a partir de una URL con WeasyPrint en Django
Generar un PDF a partir de una URL con WeasyPrint en Django

Generar PDF con una plantilla HTML de Django (render_to_string)

El flujo más habitual en Django es renderizar una plantilla con datos dinámicos usando render_to_string() y luego pasarle el HTML resultante a WeasyPrint. De esta forma, el PDF contiene exactamente el mismo contenido que mostraría tu vista normal, pero exportado como documento descargable.

Supongamos que tienes una plantilla report.html con datos dinámicos. Puedes adaptar tu vista así:

from django.template.loader import render_to_string
from django.http import HttpResponse
from weasyprint import HTML

def generar_pdf(request):
    # Renderizamos la plantilla con el contexto necesario
    html_string = render_to_string('report.html', {'usuario': 'María', 'total': 125})
    html = HTML(string=html_string)

    # Devolvemos el PDF directamente en la respuesta HTTP
    response = HttpResponse(content_type='application/pdf')
    response['Content-Disposition'] = 'inline; filename="reporte.pdf"'
    html.write_pdf(target=response)
    return response

El valor inline en Content-Disposition hace que el navegador muestre el PDF directamente en la pestaña. Si prefieres forzar la descarga, cámbialo por attachment.

Personalizar el tamaño de página y los estilos CSS

WeasyPrint permite pasar hojas de estilo adicionales mediante el parámetro stylesheets del método write_pdf(). Esto es especialmente útil para definir el tamaño y los márgenes de la página sin modificar la plantilla HTML base:

from weasyprint import HTML, CSS

HTML(string=html_string).write_pdf(
    filename,
    stylesheets=[CSS(string='@page { size: A3; margin: 1cm }')]
)

También puedes sobrescribir tipografías globales sin tocar la plantilla:

HTML('http://weasyprint.org/').write_pdf(
    '/tmp/weasyprint-website.pdf',
    stylesheets=[CSS(string='body { font-family: serif !important }')]
)

En mi caso, suelo mantener un archivo CSS dedicado solo para impresión (print.css), con fuentes, márgenes y saltos de página ajustados. Lo paso directamente a stylesheets usando CSS(filename='ruta/print.css') en lugar de CSS(string='...') cuando el archivo de estilos es extenso. Puedes explorar todas las opciones disponibles en la documentación oficial de WeasyPrint.

Guardar el archivo PDF generado en el servidor

Si en lugar de devolver el PDF al navegador prefieres guardarlo en el servidor para servirlo más tarde o adjuntarlo a un correo electrónico, simplemente pasa la ruta de destino a write_pdf():

html.write_pdf(target='media/reportes/reporte.pdf')

Asegúrate de que el directorio exista antes de escribir. Puedes combinarlo con os.makedirs() o con el sistema de almacenamiento de Django (default_storage) para un manejo más robusto en producción.

Recomendaciones para plantillas complejas

Si tu diseño es visualmente complejo (por ejemplo, una factura con logos, tablas y estilos personalizados), ten en cuenta estas consideraciones antes de desplegar:

  • Usa rutas absolutas para imágenes y hojas de estilo. WeasyPrint no puede resolver rutas relativas sin un contexto de base URL. Pásale el parámetro base_url:

    HTML(string=html_string, base_url=request.build_absolute_uri())
  • Evita dependencias de JavaScript en las plantillas que vayas a convertir a PDF. WeasyPrint no ejecuta JS, así que frameworks como React, Vue o Alpine.js no funcionarán. El PDF se genera a partir del HTML estático resultante del renderizado de Django.
  • Prueba localmente antes de desplegar, especialmente para validar que las fuentes externas y los estilos se carguen correctamente.
  • Si usas fuentes personalizadas (por ejemplo, de Google Fonts), descárgalas y sírvelas de forma local. Las peticiones externas desde WeasyPrint pueden fallar en entornos de producción sin acceso a internet saliente.

Alternativas a WeasyPrint para generar PDFs en Django

Aunque WeasyPrint es mi opción favorita, es útil conocer el ecosistema completo para elegir la herramienta adecuada según el proyecto.

LibreríaVentajasLimitaciones
WeasyPrintRenderizado preciso, soporte CSS3, multiplataforma, convierte HTML directamenteRequiere dependencias externas del sistema (GTK, Pango, Cairo)
xhtml2pdfLigera, fácil de instalar, sin dependencias externasSoporte CSS muy limitado (solo CSS2), resultados menos fieles al diseño
ReportLabMuy potente para PDFs personalizados con gráficos, tablas y coordenadas precisasNo convierte HTML directamente; requiere construir el PDF de forma programática

En resumen: usa xhtml2pdf si solo necesitas algo rápido y sin dependencias del sistema para un documento sencillo; opta por ReportLab si necesitas control total del layout y resultados pixel-perfect (por ejemplo, documentos fiscales o con coordenadas exactas); y usa WeasyPrint para la mayoría de proyectos Django donde quieras aprovechar tus plantillas HTML con soporte CSS3 real.

Errores comunes al usar WeasyPrint en Django y cómo solucionarlos

OSError: no library called "cairo"

Este es el error más frecuente en Windows. Aparece cuando GTK no está correctamente instalado o su directorio bin no está en el PATH del sistema. Reinstala el GTK for Windows Runtime Environment Installer y reinicia el sistema.

Imágenes o estilos que no aparecen en el PDF

WeasyPrint necesita rutas absolutas para acceder a imágenes y hojas de estilo. Si el PDF se genera en blanco o sin estilos, asegúrate de pasar el parámetro base_url:

HTML(string=html_string, base_url=request.build_absolute_uri())

Estilos CSS que no se aplican correctamente

WeasyPrint solo interpreta CSS válido según el estándar. Si algún estilo no se refleja en el PDF, valida tus hojas de estilo con el W3C CSS Validator y revisa que no estés usando propiedades no soportadas (como propiedades propietarias de navegadores o características CSS muy recientes aún no implementadas en WeasyPrint).

Conclusión

Generar un PDF desde una plantilla HTML en Django es mucho más sencillo de lo que parece cuando eliges las herramientas adecuadas. En mi experiencia, WeasyPrint es la opción más equilibrada: permite reutilizar tus plantillas Django existentes, soporta CSS3 de forma real y produce PDFs estables y bien formateados en cualquier plataforma con una configuración mínima.

Si necesitas precisión absoluta en el layout (por ejemplo, documentos fiscales o con coordenadas exactas), vale la pena explorar ReportLab. Pero para la gran mayoría de proyectos —facturas, reportes, certificados— WeasyPrint es más que suficiente y te ahorrará mucho tiempo de desarrollo.

Preguntas frecuentes sobre generación de PDFs en Django

  • ¿Cuál es la mejor librería para generar PDF en Django?
    • Depende del caso de uso. WeasyPrint ofrece el mejor balance entre potencia, soporte CSS y simplicidad de integración con el sistema de plantillas de Django. Es la opción recomendada para la mayoría de proyectos.
  • ¿Cómo aplicar estilos CSS al PDF generado con WeasyPrint?
    • Añadiendo una hoja de estilos mediante el parámetro stylesheets del método write_pdf(). Puedes usar CSS(string='...') para estilos inline o CSS(filename='...') para un archivo CSS externo.
  • ¿Se puede generar un PDF desde una plantilla HTML en Django?
    • Sí, es la forma más práctica y recomendada: renderizas la plantilla con render_to_string() para obtener el HTML como string y luego lo conviertes con WeasyPrint en unas pocas líneas.
  • ¿Qué diferencias hay entre WeasyPrint y xhtml2pdf?
    • xhtml2pdf es más simple y no requiere dependencias externas del sistema, pero su soporte CSS es muy limitado (CSS2). WeasyPrint soporta CSS3 completo y produce resultados mucho más fieles al diseño original.
  • ¿WeasyPrint funciona en producción con Django?
    • Sí, pero asegúrate de instalar las dependencias del sistema en tu servidor (o imagen Docker) y de usar rutas absolutas para recursos estáticos mediante el parámetro base_url al instanciar la clase HTML().

Siguiente paso: cómo integrar CKEditor 5 en Django

Aprende a generar PDFs desde plantillas HTML en Django usando WeasyPrint. Instalación en Windows, macOS y Linux, ejemplos con render_to_string y comparativa con xhtml2pdf y ReportLab.


Únete a la comunidad de desarrolladores que han decidido dejar de picar código y empezar a construir productos reales. Recibe mis mejores trucos de arquitectura cada semana:

Acepto recibir anuncios de interes sobre este Blog.