Cómo Convertir HTML a PDF en Rust
Convertir archivos HTML o cadenas HTML sin procesar a PDF es un requisito común para facturas, informes y recibos. Rust no tiene un motor de renderizado incorporado para esto, y escribir uno no es un proyecto secundario realista. El análisis de HTML es la parte fácil. El análisis de CSS, el diseño y la paginación son donde el trabajo nunca termina, lo que hace que un navegador sea una opción natural para la generación de PDF en Rust. Este tutorial convierte HTML a PDF en Rust con el crate de código abierto headless_chrome, que permite que Chrome haga el renderizado y devuelve el PDF terminado a tu programa Rust.
Crate de Chrome sin Interfaz Gráfica para Rust
headless_chrome es un crate de Rust con licencia MIT que controla un navegador Chrome o Chromium a través del Protocolo DevTools de Chrome. Puede abrir páginas, hacer clic en elementos, tomar capturas de pantalla y llamar a la función incorporada de impresión a PDF de Chrome. Como la página es renderizada por un navegador real, los diseños CSS, las fuentes web y JavaScript funcionan igual que en Chrome.
Chrome también puede imprimir una página directamente desde la línea de comandos con --print-to-pdf. Eso es solo una llamada CLI, por lo que los bytes se guardan en disco en lugar de en tu programa, y las opciones de impresión a las que puedes acceder son limitadas. En cambio, controlar el Protocolo DevTools mantiene los bytes en tu programa y deja que toda la plataforma web haga el diseño. Es el mismo protocolo sobre el que se construyen las bibliotecas equivalentes en cualquier otro lenguaje. El crate es mantenido por la comunidad de Rust, así que el soporte proviene de su rastreador de problemas en GitHub.
Requisitos Previos
Para crear un convertidor de HTML a PDF en Rust, asegúrate de tener los siguientes requisitos previos:
- Rust 1.85 o posterior. Instala el conjunto de herramientas de Rust con rustup. En Windows, el conjunto de herramientas MSVC también necesita una instalación de Visual Studio, porque
rustcutiliza su enlazador y bibliotecas. - Google Chrome, Chromium o Microsoft Edge instalados.
headless_chromebusca el navegador en elPATH, en la variable de entornoCHROMEy en Windows en el registro, usando Edge como alternativa. - Conocimientos básicos de Rust y Cargo.
Este tutorial fue probado con Rust 1.98.1, headless_chrome 1.0.22 y Chrome 153 en Windows 11. El mismo código funciona en Linux y macOS.
Crear un Proyecto Rust HTML a PDF con Cargo
Crea el proyecto binario y añade ambas dependencias desde una terminal:
cargo new html_to_pdf
cd html_to_pdf
cargo add headless_chrome urlencoding
El paso 3 utiliza el crate urlencoding para pasar la cadena HTML a Chrome como una data URL.

Comprobando Cargo.toml
Después de ejecutar cargo add, ambos crates aparecen bajo [dependencies] en el archivo Cargo.toml:
[package]
name = "html_to_pdf"
version = "0.1.0"
edition = "2024"
[dependencies]
headless_chrome = "1.0.22"
urlencoding = "2.1.3"

La característica predeterminada offline del crate utiliza un navegador ya instalado. Si la máquina de destino no tiene Chrome, habilita la característica fetch en su lugar (cargo add headless_chrome --features fetch) y el crate puede descargar una versión de Chromium por ti.
Pasos para Convertir HTML a PDF en Rust
Paso 1: Importar los Crates
Abre src/main.rs y reemplaza su contenido con las importaciones que el programa necesita. Browser y LaunchOptions inician Chrome, y PrintToPdfOptions controla la salida PDF:
use std::fs;
use headless_chrome::types::PrintToPdfOptions;
use headless_chrome::{Browser, LaunchOptions};
Paso 2: Iniciar Chrome sin Interfaz Gráfica
A continuación, inicia un navegador sin interfaz gráfica y abre una pestaña. main devuelve un Result para que cada llamada pueda usar el operador ? en lugar de unwrap:
fn main() -> Result<(), Box<dyn std::error::Error>> {
// Launch a headless Chrome instance
let browser = Browser::new(LaunchOptions {
headless: true,
..Default::default()
})?;
// Open a new tab to load the HTML into
let tab = browser.new_tab()?;
Browser::default() da el mismo resultado con menos código. LaunchOptions se muestra aquí porque es donde puedes establecer el tamaño de la ventana, la ruta de Chrome o la bandera de sandbox cuando lo necesites.
Paso 3: Establecer el Contenido HTML
Ahora proporciona el HTML que debe convertirse en PDF. La sintaxis de cadena sin procesar de Rust r#"..."# mantiene las comillas en el HTML legibles:
let html = r#"
<html>
<head>
<style>
body { font-family: Arial, sans-serif; margin: 40px; }
h1 { color: #2a5db0; }
table { border-collapse: collapse; width: 100%; }
th, td { border: 1px solid #ccc; padding: 8px; text-align: left; }
th { background-color: #f0f4fa; }
</style>
</head>
<body>
<h1>Hello, World!</h1>
<p>This PDF was generated from an HTML string in Rust.</p>
<table>
<tr><th>Item</th><th>Quantity</th><th>Price</th></tr>
<tr><td>Widget</td><td>2</td><td>$10.00</td></tr>
<tr><td>Gadget</td><td>1</td><td>$25.00</td></tr>
</table>
</body>
</html>
"#;
// Load the HTML string as a data URL and wait for the page to finish loading
let data_url = format!("data:text/html;charset=utf-8,{}", urlencoding::encode(html));
tab.navigate_to(&data_url)?.wait_until_navigated()?;
print_to_pdf no tiene opción HTML. Imprime lo que la pestaña está mostrando, y el crate no tiene un método para establecer el contenido de la página directamente, por lo que la cadena HTML se codifica en porcentaje en una URL data: y la pestaña navega hacia ella.
wait_until_navigated luego bloquea hasta que la página esté lista, y no se detiene en el evento de carga. El crate activa los eventos de ciclo de vida de Chrome y borra su bandera de navegación en networkAlmostIdle, el hito del ciclo de vida del navegador que llega una vez que las solicitudes que la página obtuvo (red inactiva) han terminado. Para cuando la pestaña informa que la navegación está completa, normalmente ya están cargadas las fuentes web y las imágenes tardías.
Paso 4: Convertir HTML a PDF
Con la página cargada, llama a print_to_pdf. PrintToPdfOptions corresponde a la configuración de impresión de Chrome, y cada campo es opcional:
// Print the page to PDF with background colors and 0.4 inch margins
let options = PrintToPdfOptions {
print_background: Some(true),
margin_top: Some(0.4),
margin_bottom: Some(0.4),
margin_left: Some(0.4),
margin_right: Some(0.4),
..Default::default()
};
Los márgenes y tamaños de papel están en pulgadas. Sin paper_width y paper_height, Chrome utiliza tamaño Carta de EE. UU. (8.5 x 11 pulgadas). Chrome no imprimirá colores de fondo ni imágenes a menos que se lo indiques. print_background está desactivado por defecto, y sin él, el sombreado del encabezado de la tabla se omite en el PDF.
Los campos de configuración de página (landscape, scale, page_ranges y las plantillas de encabezado y pie de página) tendrán su propia sección más adelante en este tutorial.
Paso 5: Obtener la salida como un vector de bytes
print_to_pdf devuelve el documento terminado como un Vec<u8> almacenado en memoria. Aún no se ha escrito nada en disco, por lo que los bytes pueden ir a un archivo, al cuerpo de una respuesta HTTP o a un almacenamiento en la nube:
let pdf_data: Vec<u8> = tab.print_to_pdf(Some(options))?;
Paso 6: Guardar el archivo PDF
Para guardar el PDF, escribe el vector de bytes en un archivo con std::fs::write, que crea el archivo, escribe todos los bytes y lo cierra en una sola llamada:
// Write the PDF bytes to disk
fs::write("output.pdf", &pdf_data)?;
println!("PDF saved successfully ({} bytes).", pdf_data.len());
Ok(())
}
Paso 7: Limpieza
A diferencia de la API C de wkhtmltopdf, no hay funciones destroy o deinit que llamar. Cuando browser sale del alcance al final de main, su implementación de Drop apaga el proceso de Chrome y elimina la carpeta de perfil temporal que creó. Si un paso falla y ? retorna antes, la misma limpieza aún se ejecuta.
En un servicio de larga duración, mantén un Browser vivo y abre una nueva pestaña por documento en lugar de iniciar un nuevo proceso de Chrome para cada solicitud.
Paso 8: Ejecutar el código y generar el archivo PDF
Compila y ejecuta el proyecto desde la carpeta del proyecto:
cargo run
La primera compilación compila 143 crates, lo que tomó 45 segundos en la máquina utilizada aquí. El programa luego imprime el tamaño del archivo generado:

El archivo output.pdf se guarda en la carpeta del proyecto. Los estilos CSS, incluido el color del encabezado y los bordes y fondo de la tabla, se conservan:

Aquí está el propio output.pdf generado:
Convertir una URL o archivo HTML a PDF en Rust
Las mismas llamadas navigate_to y print_to_pdf funcionan para páginas web y archivos HTML locales. Para archivos locales, agrega el paquete url con cargo add url para que puedas convertir la ruta del archivo en una URL file:// válida en cualquier sistema operativo.
El siguiente ejemplo lee una plantilla local, así que guarda esto junto a Cargo.toml como invoice.html:
<html>
<head>
<style>
body { font-family: Arial, sans-serif; margin: 30px; }
.box { background: #2a5db0; color: #fff; padding: 16px; }
</style>
</head>
<body>
<div class="box"><h2>Invoice #1024</h2></div>
<p>Loaded from a local HTML file.</p>
</body>
</html>
Guarda el siguiente programa como examples/url_and_file.rs y ejecútalo con cargo run --example url_and_file:
use std::fs;
use headless_chrome::types::PrintToPdfOptions;
use headless_chrome::Browser;
use url::Url;
fn main() -> Result<(), Box<dyn std::error::Error>> {
let browser = Browser::default()?;
let tab = browser.new_tab()?;
// Convert a live web page to PDF
tab.navigate_to("https://doc.rust-lang.org/book/")?
.wait_until_navigated()?;
let url_pdf = tab.print_to_pdf(None)?;
fs::write("url.pdf", url_pdf)?;
// Convert a local HTML file to PDF
let path = fs::canonicalize("invoice.html")?;
let file_url = Url::from_file_path(&path).map_err(|_| "invalid file path")?;
tab.navigate_to(file_url.as_str())?.wait_until_navigated()?;
let options = PrintToPdfOptions {
landscape: Some(true),
print_background: Some(true),
..Default::default()
};
fs::write("invoice.pdf", tab.print_to_pdf(Some(options))?)?;
println!("Saved url.pdf and invoice.pdf");
Ok(())
}
Una pestaña maneja ambos documentos uno tras otro. La URL se imprime con los valores predeterminados de Chrome, y la factura local se imprime en horizontal con sus colores de fondo:

La página web capturada en url.pdf:
Y el archivo HTML local impreso en invoice.pdf en horizontal:
Guarda las plantillas con un nombre .html, porque Chrome decide cómo tratar un archivo local según la extensión de entrada. El mismo marcado guardado como .txt se imprimió como etiquetas visibles en lugar de una página renderizada.
Tamaño de página, números de página y saltos de página
PrintToPdfOptions refleja el cuadro de diálogo de impresión de Chrome, y sus valores admitidos son los que el propio cuadro de diálogo ofrece. landscape: Some(true) cambia a modo horizontal, scale toma un factor de zoom donde 1.0 es tamaño completo, y page_ranges toma una cadena basada en uno como "1-5, 8, 11-13".
Los números de página pueden venir de cualquier lado. Dale a Chrome una plantilla de pie de página y sustituirá pageNumber y totalPages en cada página:
let options = PrintToPdfOptions {
display_header_footer: Some(true),
header_template: Some("<span></span>".into()),
footer_template: Some(
"<div style='font-size:10px;width:100%;text-align:center'>Page <span class='pageNumber'></span> of <span class='totalPages'></span></div>".into()),
margin_bottom: Some(0.6),
..Default::default()
};
La ruta CSS también funciona. Chrome Platform Status enumera las cajas de margen @page en el hito 131, por lo que la orientación escrita antes de eso es comportamiento histórico. En Chrome 153, esta regla de contador de página sola numeró cada página de un documento de cuatro páginas:
@page { @bottom-center { content: "Page " counter(page); } }
Controlar dónde cae un salto de página también es CSS ordinario. Un documento de prueba de seis tarjetas mostró la diferencia. Sin la propiedad, la primera página terminaba a la mitad de la tercera tarjeta, y el resto de esa tarjeta continuaba en la página dos. Al agregar la propiedad CSS break-inside, cada tarjeta pasó a la siguiente página completa, dos por página, sin que ninguna se dividiera:
.card { break-inside: avoid; }
Qué incluye Chrome en el PDF
Dos opciones cambian la estructura del archivo, no el aspecto de la página:
let options = PrintToPdfOptions {
generate_document_outline: Some(true),
generate_tagged_pdf: Some(true),
..Default::default()
};
generate_document_outline convierte tus encabezados en marcadores PDF. Un informe con un h1 y dos encabezados h2 produjo un esquema de documento de tres entradas con la opción activada, y ningún esquema en absoluto con la opción desactivada.
generate_tagged_pdf solicita un PDF etiquetado, la estructura que leen los lectores de pantalla y los verificadores PDF/UA. La documentación del Protocolo DevTools indica su valor predeterminado como "embedder choice" en lugar de desactivado, y la prueba aquí coincidió con eso. Con ambas opciones desactivadas, la salida aún contenía un árbol de estructura y mantenía el idioma del documento desde <html lang="en">. Establece ese atributo en tus plantillas de cualquier manera, y revisa tu propia salida antes de confiar en la bandera.
Las fuentes se incrustan con subconjuntos de fuentes, por lo que una página configurada en Georgia produjo AAAAAA+Georgia-Bold y BAAAAA+Georgia en lugar de toda la familia. Una fotografía JPEG se almacenó como JPEG, no se volvió a codificar.
Uso de Headless Chrome en un servicio Rust
El crate es bloqueante, por eso ninguno de los códigos anteriores está escrito como un async fn main. Si tu servicio ya tiene un runtime async como Tokio, mantén el navegador fuera del reactor llamándolo dentro de tokio::task::spawn_blocking, para que una renderización lenta no pueda bloquear el ejecutor.
Nada se consulta para siempre. Cada operación de pestaña se ejecuta contra un tiempo de espera y devuelve un error en lugar de quedarse colgada, por lo que una página que nunca se estabiliza no puede bloquear un trabajador.
Las líneas de inicio y cierre de Chrome aparecen en cualquier servicio que instale un logger, porque el crate informa a través del crate log. Para eliminar los logs de la capa del navegador sin silenciar los tuyos propios, filtra por destino, por ejemplo RUST_LOG=info,headless_chrome=warn.
Problemas comunes al convertir HTML a PDF en Rust
Estos son los modos de fallo que aparecen en producción:
- Contenido renderizado por JavaScript:
wait_until_navigatedretorna una vez que la red se queda en silencio, lo cual no es lo mismo que un gráfico terminando de dibujarse. Llama atab.wait_for_element("#report-ready")sobre un elemento que la página añade cuando termina, y luego imprime. - Tiempos de espera: las operaciones de pestaña tienen un tiempo de espera de 20 segundos por defecto. Aumenta el límite con
tab.set_default_timeout(std::time::Duration::from_secs(60))para páginas lentas. - Cadenas HTML grandes: Chrome limita las URLs a 2 MB, y eso incluye las URLs
data:. Para documentos más grandes, escribe el HTML en un archivo temporal y cárgalo con una URLfile://como se mostró arriba. - Docker y contenedores Linux: el sandbox de Chrome falla al iniciar cuando el proceso se ejecuta como root, y la guía de solución de problemas de Puppeteer desaconseja fuertemente ejecutar sin sandbox. Añade un usuario sin privilegios a la imagen y mantén el sandbox activado, y configura
sandbox: falseenLaunchOptionssolo cuando no tengas alternativa. De cualquier manera, la imagen necesita las bibliotecas del sistema de Chrome. - Despliegue: cada servidor que ejecute el programa necesita un navegador compatible, por lo que Chrome pasa a formar parte de tu despliegue aunque el código Rust se compile en un solo binario.
Otras formas de convertir HTML a PDF en Rust
headless_chrome no es la única ruta. Cuál se adapta depende de si tus documentos necesitan JavaScript y cuántos renders a la vez.
Basados en Chromium, como este tutorial
html2pdf se describe a sí mismo como solo una CLI sobre el crate headless_chrome, y también se distribuye como una biblioteca cuya API es async y se ejecuta en tokio, lo que te ahorra escribir el wrapper spawn_blocking tú mismo.
Gotenberg mueve el navegador completamente fuera de tu proceso. Es una API basada en Docker para convertir documentos a PDF: Chromium maneja URLs, HTML y Markdown, LibreOffice maneja formatos de oficina, y tu servicio Rust envía un archivo por HTTP y recibe un PDF de vuelta. Eso mantiene Chrome fuera del despliegue de tu binario a costa de ejecutar un servicio junto a él.
Motores Rust sin navegador
Headless Chrome puede ser intensivo en recursos para la generación concurrente de PDF, porque cada conversión necesita un proceso de navegador y la memoria asociada. Dos proyectos en Rust abordan este problema directamente.
htmltopdf es un motor con licencia MIT que renderiza en un solo hilo sin subprocesos, y su README lo describe como diseñado para alta concurrencia y bajo uso de RAM. El README informa un pico de aproximadamente 92 MB de RAM frente a unos 846 MB para el proceso principal de Chromium en un solo documento de 1.8 MB. Para 20 conversiones concurrentes, informa 12.75 PDF/s a 1.25 GiB frente a 1.18 PDF/s a 9.35 GiB de Chromium, medido con /usr/bin/time -l en Apple Silicon. Estas son pruebas del propio proyecto con sus propios archivos de prueba, y no se reprodujeron para este artículo. El crate no está en crates.io, por lo que se instala desde el repositorio, y el manejo de JavaScript es una etapa previa al diseño, opcional y limitada, no un motor completo.
Fulgur es otro motor HTML a PDF en Rust que omite el navegador. Es Apache-2.0, e integra Blitz para el análisis HTML, resolución de estilos y maquetación con Krilla para la generación de PDF. Fulgur admite un subconjunto seleccionado de HTML y CSS, rastreado propiedad por propiedad en su documento de soporte CSS, y su lista de características no incluye motor de JavaScript. Lo que sí cubre es el lado paginado, incluyendo contadores de página, encabezados en ejecución, cajas de margen, break-inside, PDF etiquetado y subconjunto de fuentes. El pipeline de renderizado de Fulgur incluye un renderizado en 2 pasadas para mayor precisión, por lo que las referencias cruzadas como target-counter() se resuelven antes de escribir el PDF.
Motores comerciales
Prince admite CSS Paged Media para la creación compleja de PDF, incluyendo reglas @page, cajas de margen de página y un contador de página predefinido para encabezados y pies de página en ejecución. Prince es un software comercial que se licencia, no un crate que se agrega con Cargo.
Cuál se adapta
Durante años, la regla general era que las opciones nativas de Rust para HTML a PDF tenían soporte limitado para CSS y JavaScript, por lo que los motores puros de Rust solo servían para documentos simples. La parte de CSS de esa afirmación ha quedado obsoleta. htmltopdf enumera flexbox, grid, tablas con rowspans y @font-face, y Fulgur cubre los medios paginados de principio a fin. JavaScript es donde aún existe la brecha.
Lo que genera tu documento decide la elección. Si un servidor renderiza el HTML y el estilo es CSS, un motor sin navegador elimina Chrome de tu despliegue junto con su memoria. Si tus páginas dibujan gráficos en el navegador o dependen de scripts propios de una aplicación web, mantén un navegador en el flujo, que es lo que hace este tutorial.
IronPDF para Rust (Próximamente)
IronPDF para Rust está en desarrollo. La biblioteca planificada creará PDFs a partir de HTML y manipulará PDFs existentes, todo desde código Rust.
Únete al programa beta de IronPDF para Rust para obtener acceso anticipado y ayudar a definir la API.
Archivo HTML a archivo PDF en C#
IronPDF
IronPDF HTML-to-PDF Conversion Library es una biblioteca C# para .NET y .NET Core que genera documentos PDF a partir de contenido HTML. Incluye su propio motor de renderizado Chrome, por lo que no hay que instalar, iniciar ni cerrar un navegador por separado.
IronPDF maneja más que documentos HTML simples. Renderiza páginas web complejas con estilos CSS y JavaScript, y también edita, combina, firma y protege PDFs después de crearlos.
El mismo trabajo con IronPDF, convirtiendo una cadena HTML a PDF en C#:
using IronPdf;
// Instantiate Renderer
var renderer = new ChromePdfRenderer();
// Create PDF content from an HTML string using C#
var pdf = renderer.RenderHtmlAsPdf("<h1>Hello World</h1>");
// Export to a file or Stream
pdf.SaveAs("output.pdf");Imports IronPdf
' Instantiate Renderer
Private renderer = New ChromePdfRenderer()
' Create PDF content from an HTML string using C#
Private pdf = renderer.RenderHtmlAsPdf("<h1>Hello World</h1>")
' Export to a file or Stream
pdf.SaveAs("output.pdf")Imports IronPdf
' Instantiate Renderer
Private renderer = New ChromePdfRenderer()
' Create PDF content from an HTML string using C#
Private pdf = renderer.RenderHtmlAsPdf("<h1>Hello World</h1>")
' Export to a file or Stream
pdf.SaveAs("output.pdf")La salida PDF:

Los pasos de este tutorial de Rust se corresponden con configuraciones individuales de IronPDF. La configuración de página se cubre en márgenes personalizados y tamaño de papel personalizado, y el problema de espera de JavaScript se maneja con los retardos de renderizado WaitFor. Convertir una URL a PDF o un archivo HTML a PDF requiere solo una llamada a método cada uno, y encabezados y pies de página con números de página no necesitan plantillas HTML. Para una guía completa, consulta el tutorial de HTML a PDF, o lee cómo funciona la misma tarea en HTML a PDF en C++.
Puedes probar todo esto con una Prueba gratuita de la funcionalidad completa de IronPDF. Funciona durante 30 días, no requiere tarjeta de crédito y opera en servidores en vivo sin marcas de agua mientras lo evalúas. La licencia después de eso es perpetua, sin cuotas recurrentes, dimensionada por desarrolladores, proyectos y ubicaciones, y respaldada por una garantía de devolución de dinero de 30 días. Para comenzar, descarga IronPDF.
Curtis Chau tiene una licenciatura en Ciencias de la Computación (Carleton University) y se especializa en el desarrollo front-end con experiencia en Node.js, TypeScript, JavaScript y React. Apasionado por crear interfaces de usuario intuitivas y estéticamente agradables, disfruta trabajando con frameworks modernos y creando manuales bien estructurados y visualmente atractivos.