Введение

Создание PDF-файлов из HTML — частая задача при генерации отчётов, счетов, билетов, документов с шаблонами. Когда внешний вид важен, а данные формируются на сервере, HTML+CSS становятся отличным инструментом. Но как превратить его в PDF с точной вёрсткой? Один из лучших инструментов в Python для этого — PDFKit.

PDFKit — это Python-обёртка над популярной утилитой wkhtmltopdf, которая рендерит HTML-документы в PDF с помощью движка WebKit. Это позволяет использовать современные CSS, встроенные шрифты, SVG, таблицы, Bootstrap и даже JavaScript. В статье мы разберём всё: от установки до генерации сложных PDF-документов из HTML-шаблонов.

Основная часть

Установка

Установка библиотеки Python:

pip install pdfkit

Установка wkhtmltopdf:

Ubuntu:

sudo apt install wkhtmltopdf

macOS (через brew):

brew install --cask wkhtmltopdf

Windows: скачайте с https://wkhtmltopdf.org/downloads.html

Важно: убедитесь, что бинарник wkhtmltopdf доступен в PATH или передайте путь вручную в конфигурации.

Быстрый старт

import pdfkit
pdfkit.from_url("https://example.com", "out.pdf")

Также можно использовать:

pdfkit.from_file("input.html", "out.pdf")
pdfkit.from_string("<h1>Hello</h1>", "out.pdf")

Конфигурация пути к бинарнику (если wkhtmltopdf не в PATH)

config = pdfkit.configuration(wkhtmltopdf='/usr/local/bin/wkhtmltopdf')
pdfkit.from_string("<h1>Hi</h1>", "out.pdf", configuration=config)

Работа с опциями

Вы можете управлять стилями, форматами страниц, отступами, масштабом и метаданными:

options = {
    'page-size': 'A4',
    'margin-top': '0.75in',
    'margin-right': '0.75in',
    'margin-bottom': '0.75in',
    'margin-left': '0.75in',
    'encoding': "UTF-8",
    'no-outline': None
}

pdfkit.from_string(html_str, "out.pdf", options=options)

Генерация PDF из Django / Flask шаблонов

Flask:

from flask import render_template
html = render_template("invoice.html", context=data)
pdfkit.from_string(html, "invoice.pdf")

Django:

from django.template.loader import render_to_string
html = render_to_string("template.html", context)
pdfkit.from_string(html, "out.pdf")

Примеры параметров `wkhtmltopdf`

Параметр	Описание
`--header-html`	Вставить HTML в шапку каждой страницы
`--footer-html`	Аналогично для подвала
`--zoom`	Масштаб страницы
`--print-media-type`	Использовать media CSS как при печати
`--dpi`	Плотность (для чёткости шрифтов)

Генерация PDF в памяти (например, для отправки через API)

pdf = pdfkit.from_string("<h1>Hello</h1>", False)

Результат — байты PDF, можно возвращать как application/pdf.

Интеграция с API и CI/CD

PDFKit подходит для генерации документов в:

REST API (FastAPI, Flask, Django)
Lambda-функциях
Отчётности в Airflow, Prefect
CI-пайплайнах для генерации документации

Ограничения и альтернативы

Минусы:

Требует внешней зависимости (wkhtmltopdf)
Не поддерживает интерактивные элементы
Иногда нестабилен в контейнерах

Альтернативы:

WeasyPrint (рэндер на Cairo)
xhtml2pdf (меньше CSS, но без зависимости от wkhtmltopdf)

Полный список функций и методов библиотеки `pdfkit` для Python, сгруппированных по категориям

Создание PDF из различных источников

Функция	Описание
`pdfkit.from_url(url, output_path, options=None)`	Конвертирует страницу по URL в PDF.
`pdfkit.from_file(input, output_path, options=None)`	Конвертирует HTML-файл в PDF.
`pdfkit.from_string(string, output_path, options=None)`	Конвертирует HTML-строку в PDF.
`pdfkit.configuration(...)`	Устанавливает путь к `wkhtmltopdf` (если он не в PATH).

Параметры output_path

Значение	Поведение
`"output.pdf"`	Сохраняет результат в указанный файл.
`False`	Возвращает PDF в виде `bytes`.
`None`	Возвращает PDF как байтовую строку (используется в API и Web-сервисах).

Настройка wkhtmltopdf

Параметр	Описание
`pdfkit.configuration(wkhtmltopdf="/usr/bin/wkhtmltopdf")`	Указывает путь к исполняемому файлу `wkhtmltopdf`.
`config = pdfkit.configuration(...)`	Конфигурация передаётся в методы через параметр `configuration=config`.
`wkhtmltopdf`	Должен быть установлен отдельно: `sudo apt install wkhtmltopdf` или скачан с официального сайта.

Основные опции генерации PDF (через options={})

Параметр	Описание
`'page-size': 'A4'`	Размер страницы (A4, Letter и т.д.).
`'margin-top': '10mm'`	Верхний отступ.
`'margin-bottom': '10mm'`	Нижний отступ.
`'margin-left': '10mm'`	Левый отступ.
`'margin-right': '10mm'`	Правый отступ.
`'encoding': 'UTF-8'`	Устанавливает кодировку текста.
`'no-outline': None`	Отключает оглавление.
`'zoom': '1.3'`	Масштаб страницы.
`'print-media-type': None`	Применяет стили `@media print` из CSS.

Пример использования: из строки

Пример: из URL

Пример: из HTML-файла

Заключение

PDFKit — одно из самых удобных решений в Python для генерации PDF из HTML. Его мощь заключается в том, что вы можете писать адаптивные HTML/CSS-документы, применять Bootstrap или Tailwind, а потом превращать их в точные PDF-файлы для печати, отправки и архивации. Главное — правильно настроить wkhtmltopdf и параметры рендеринга.