.NET AYUDA

Cómo Convertir HTML a PDF en Rust

Curtis Chau
Curtis Chau
Actualizado: 18 de octubre de 2026

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:

  1. 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 rustc utiliza su enlazador y bibliotecas.
  2. Google Chrome, Chromium o Microsoft Edge instalados. headless_chrome busca el navegador en el PATH, en la variable de entorno CHROME y en Windows en el registro, usando Edge como alternativa.
  3. 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
SHELL

El paso 3 utiliza el crate urlencoding para pasar la cadena HTML a Chrome como una data URL.

Cómo convertir HTML a PDF en Rust: Figura 1 - Creando el proyecto y agregando dependencias

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"
Text

Cómo convertir HTML a PDF en Rust: Figura 2 - Dependencias en Cargo.toml

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};
Rust

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()?;
Rust

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()?;
Rust

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()
    };
Rust

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))?;
Rust

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(())
}
Rust

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
SHELL

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:

Cómo convertir HTML a PDF en Rust: Figura 3 - salida de cargo run

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:

Cómo convertir HTML a PDF en Rust: Figura 4 - Salida PDF

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>
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(())
}
Rust

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:

Cómo convertir HTML a PDF en Rust: Figura 5 - URL y archivo HTML convertidos a PDF

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()
};
Rust

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); } }
CSS

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; }
CSS

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()
};
Rust

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_navigated retorna una vez que la red se queda en silencio, lo cual no es lo mismo que un gráfico terminando de dibujarse. Llama a tab.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 URL file:// 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: false en LaunchOptions solo 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");

La salida PDF:

Cómo convertir HTML a PDF en Rust: Figura 6 - Salida de IronPDF

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.

Leer más

Artículos relacionados