WeasyPrint: подробный обзор генератора PDF из HTML и CSS

WeasyPrint — движок для преобразования HTML/CSS в PDF, а не программа для чтения или визуального редактирования документов. Его специализация — печатная вёрстка: страницы, поля, колонтитулы, нумерация, сноски, закладки, ссылки и стандартизованные PDF-профили. В версии 70.0 проект остаётся активным Python-инструментом для автоматической генерации документов, но требует учитывать собственную модель CSS и нативные зависимости.

Скачать WeasyPrint

Безопасный путь получения зависит от платформы. Для Python-проектов основной канал — пакет WeasyPrint 70.0 в PyPI; Linux также может использовать пакеты дистрибутива. На macOS документация рекомендует Homebrew, а для Windows публикуется готовый executable последнего релиза. Для встраивания как Python-библиотеки лучше работать в отдельном virtual environment и фиксировать версию в зависимостях проекта.

Для Windows есть важная оговорка: документация предупреждает о возможных ложных антивирусных срабатываниях на официальный executable. Безопасная тактика — получать сборку из официального релиза, сверять актуальность версии и при спорном детекте сообщать его поставщику защитного ПО; отключать антивирус ради установки не требуется.

Что такое WeasyPrint

WeasyPrint — layout-движок HTML/CSS, ориентированный на пагинацию и печатный PDF, а не на отображение веб-страницы в окне браузера. Проект создан Kozea; сопровождение, профессиональная поддержка и работа с сообществом связаны с CourtBouillon и участниками проекта. Это открытое ПО на BSD 3-Clause с CLI и Python API, без обязательной учётной записи или облачной службы для локального рендеринга.

Основная аудитория — разработчики и команды, которые уже формируют HTML либо могут поддерживать шаблоны HTML/CSS. WeasyPrint подходит для серверной генерации счетов, отчётов, сертификатов и печатных форм, где важна воспроизводимая вёрстка. Это не OCR-система, не PDF-редактор и не просмотрщик: существующий PDF не является его основным входным документом.

Текущий статус — активный. Версия 70.0 выпущена 8 сентября 2026 года как обновление безопасности и закрывает CVE-2026-55073. Разработчики особенно рекомендуют обновление при работе с недоверенными изображениями или фильтрации ресурсов через URL fetcher. Для нового внедрения разумно начинать с 70.0, а не с инструкций для 68.x–69.x.

Основные функции WeasyPrint

Пагинация и печатная CSS-вёрстка

Главная специализация — CSS Paged Media. Через @page задаются размер, ориентация, поля и margin boxes; CSS управляет разрывами, widows/orphans и именованными страницами. Running elements и named strings позволяют строить колонтитулы, а target-counter() и target-text() — ссылки на номера страниц и текст целей, что полезно для оглавлений и перекрёстных ссылок.

Сноски поддерживаются средствами CSS Generated Content for Paged Media: можно оформить вызов, маркер, область сносок и перенос. В 70.0 появилась начальная поддержка CSS Notes. Это экспериментальная спецификация, поэтому для производственного шаблона функции Notes следует применять только после проверки на конкретном макете.

Шрифты, изображения и SVG

Шрифты берутся через Pango и могут подключаться через @font-face. При записи PDF они встраиваются и по умолчанию сабсетятся, что уменьшает файл. Наличие нужного шрифта критично: пропущенные глифы обычно означают проблему с установленными шрифтами или URL ресурса, а не «кодировку PDF».

Растровые изображения обрабатываются через Pillow; SVG сохраняет преимущества векторного источника. Для изображений доступны оптимизация, ограничение JPEG quality и DPI. В 70.0 добавлены COLR emoji fonts, box-shadow и улучшения SVG, но визуально сложные ресурсы всё равно нужно проверять в конечном PDF.

PDF-функции: ссылки, закладки, вложения и формы

Готовый PDF может содержать внутренние и внешние ссылки, закладки и вложения. Заголовки h1–h6 по умолчанию участвуют в дереве закладок, а CSS bookmark-* даёт дополнительный контроль. Вложения можно добавлять через HTML/CSS и параметры CLI/API, поэтому права URL fetcher важны не только для картинок.

HTML-формы по умолчанию становятся статическим представлением, но параметр pdf_forms или CSS appearance: auto позволяет создавать интерактивные поля PDF. Поддержка таких полей зависит и от PDF-просмотрщика, поэтому форму нужно открывать в том PDF-просмотрщике, которым пользуется адресат.

PDF/A, PDF/UA, PDF/X и электронные счета

WeasyPrint 70.0 умеет выбирать варианты PDF/A-1/2/3/4, PDF/UA-1 и PDF/UA-2, а также PDF/X-1a, PDF/X-3, PDF/X-4 и PDF/X-5g; в API перечислены конкретные профили b, u и a. Есть тегирование, XMP, output intent, идентификатор PDF и управление шрифтами. Выбор профиля не гарантирует соответствие стандарта: итоговый файл нужно валидировать.

Для Factur-X/ZUGFeRD движок может собрать гибридный PDF/A-3b, если приложение подготовило требуемые RDF-метаданные и XML счёта. Сам WeasyPrint не заменяет бухгалтерскую систему и не создаёт бизнес-данные EN 16931 из ничего.

Python API и работа с отдельными страницами

Python API поддерживает прямой write_pdf и двухэтапную схему render → Document. Объект Document даёт доступ к страницам, ссылкам, закладкам и метаданным; набор страниц можно копировать и сохранять как новый PDF. Это программная операция над результатом layout, а не ручное редактирование существующего PDF.

URL fetcher определяет, как загружаются CSS, изображения и вложения. Его можно настраивать по заголовкам, тайм-аутам, разрешённым протоколам, редиректам и HTTP-ошибкам, а при необходимости заменить собственным загрузчиком. Это основной слой интеграции с авторизацией, внутренним хранилищем и сетевой политикой приложения.

Интерфейс и удобство использования

У WeasyPrint нет традиционного GUI с панелями, миниатюрами и кнопкой экспорта. Работа строится вокруг CLI, Python API, редактора HTML/CSS и внешнего PDF-просмотрщика: источник задаёт разметку, WeasyPrint выполняет вёрстку, а просмотрщик используется для контроля результата. Для автоматизации такая схема проще визуального редактора, для разовой офисной работы — сложнее.

Порог входа определяется знанием HTML/CSS и печатной разметки. @page, разрывы, колонтитулы и перекрёстные ссылки задаются декларативно; диагностические предупреждения выводятся в консоль. Удобнее всего держать маленький эталонный HTML и прогонять его после изменений шаблона или версии движка.

Локализованного интерфейса нет: параметры CLI и имена API англоязычные. Это не ограничивает язык самого документа — русский и другие письменности выводятся при наличии подходящих шрифтов; отдельно следует учитывать заявленные ограничения RTL/bidirectional layout.

Поддерживаемые форматы и совместимость

Основной вход — HTML: локальный файл, URL, файловый объект, строка в памяти или stdin. CSS может находиться в документе, подключённой таблице стилей или передаваться как user stylesheet. Для строк и нестандартных источников важно задавать base_url, иначе относительные пути к CSS, шрифтам и изображениям не разрешатся.

URL-слой работает с локальными и сетевыми ресурсами; документация упоминает HTTP, FTP и data URI. В актуальном URLFetcher можно ограничивать протоколы и редиректы, задавать тайм-аут и реакцию на HTTP-ошибки. Авторизацию, cookies и закрытое хранилище обычно подключают через собственный fetcher.

Основной документ на выходе — PDF через write_pdf. Старые описания PNG-экспорта не следует переносить на 70.0. WeasyPrint также не является конвертером PDF→Word/JPG и не открывает существующий PDF как редактируемый исходник: обратный путь должен обеспечивать другой инструмент.

CSS реализован широко прежде всего для печатной вёрстки, но не совпадает с современным браузером. Среди существенных ограничений документация отмечает RTL/bidirectional text; writing-mode не поддерживается. Flexbox годится для многих простых случаев, но не считается глубоко протестированным, а Grid имеет ограничения для subgrid, auto-fill/auto-fit, некоторых intrinsic sizing, baseline и сложной фрагментации.

WeasyPrint не предназначен для выполнения клиентского JavaScript. Если контент появляется только после JS, сначала сформируйте конечный HTML в приложении либо используйте браузерный движок рендеринга. Это одно из главных различий с Chromium Headless.

Паспорт обратимости операций

WeasyPrint разумно воспринимать как компилятор документа: редактируемым источником остаются данные, HTML, CSS, шрифты и изображения, а PDF — артефакт сборки. Поэтому шаблон, зависимости и входные данные нужно хранить отдельно; один конечный PDF не восстанавливает условия генерации и обычно не подходит для удобного обратного редактирования.

Производительность и стабильность

Документация прямо отмечает, что WeasyPrint может рендерить медленнее браузерных движков. Стоимость растёт при сочетании большого DOM с большим количеством CSS-свойств; тяжёлыми бывают многостраничные таблицы. Для серверного режима полезен долгоживущий процесс, чтобы не платить за инициализацию при каждом документе, а кэш изображений снижает повторные загрузки и обработку.

Для больших документов нельзя обещать линейное масштабирование: таблицы, grid/flex, крупные изображения и сложный CSS меняют профиль нагрузки. Раздел документации по безопасности отдельно предупреждает, что недоверенные HTML/CSS могут вызвать длительный рендеринг, огромные файлы или высокий расход памяти. В серверном контуре нужны лимиты CPU/RAM/времени и изоляция процесса.

Major-релизы могут менять визуальный результат без поломки Python API. Поэтому производственный шаблон стоит привязывать к конкретной версии, читать changelog и сравнивать эталонные PDF перед обновлением. Релизы с исправлениями безопасности при этом нельзя игнорировать: 68.0, 69.0 и 70.0 содержали исправления безопасности.

Лицензирование и версии

WeasyPrint распространяется по BSD 3-Clause. Его можно бесплатно использовать, изменять и включать в коммерческие системы при соблюдении условий лицензии и сохранении необходимых уведомлений. Отдельной платной редакции с разблокировкой функций, водяных знаков, лимита страниц или пробного периода у проекта нет.

Профессиональная поддержка отделена от лицензии ПО. CourtBouillon предлагает обращаться за приоритетной поддержкой, исправлениями, разработкой возможностей и обучением; фиксированная цена пакета на публичной странице не указана. То есть стоимость самого движка равна нулю, а коммерческое сопровождение оценивается отдельно.

Хронология развития и поддержки

Хронология важна при миграции: старые статьи могут описывать другой стек зависимостей, Windows-инструкции и API. Перед обновлением сравнивайте changelog от закреплённой версии до новой; после major-релиза прогоняйте визуальные эталоны, а после обновлений безопасности отдельно проверяйте изменившееся поведение URL fetcher и ресурсов.

Системные требования

Для WeasyPrint 70.0 официально указаны Python 3.10.0+, Pango 1.44.0+, pydyf 0.11.0+, CFFI 0.6+, tinyhtml5 2.0.0b1+, tinycss2 1.5.0+, cssselect2 0.8.0+, Pyphen 0.9.1+, Pillow 9.1.0+ и fontTools 4.59.2+. Часть Python-зависимостей ставит pip, но Pango и связанные нативные библиотеки зависят от ОС.

Linux

Документация приводит маршруты для Alpine 3.17+, Debian 11+, Fedora 39+, Ubuntu 20.04+ и Arch Linux. Системные пакеты удобны для нативных библиотек; в проекте при этом можно держать Python-пакет в venv. При ошибках рендеринга сначала сверяют версии Python/Pango и наличие шрифтов.

macOS

На macOS самый простой официальный маршрут — Homebrew. При ошибке загрузки нативной библиотеки документация предлагает проверить её расположение и при необходимости настроить DYLD_FALLBACK_LIBRARY_PATH. Отдельного минимального номера macOS на странице требований не заявлено, поэтому придумывать его не следует.

Windows

В Windows для CLI проще официальный executable. Для Python-библиотеки актуальная инструкция использует Python Install Manager, MSYS2 UCRT64 и пакет mingw-w64-ucrt-x86_64-pango; при проблеме поиска DLL может понадобиться WEASYPRINT_DLL_DIRECTORIES, указывающий на каталог UCRT64.

Что не является подтверждённым требованием

Проект не публикует универсальный минимум RAM, CPU или диска. Нагрузка зависит от шаблона, изображений, шрифтов, числа страниц и параллельных задач, поэтому фиксированные «4 ГБ RAM» или «двухъядерный процессор» без официального основания были бы недостоверны.

Карта критических зависимостей

Учётная запись и облачная служба не являются обязательными зависимостями локальной генерации. Интернет нужен для получения пакетов или удалённых ресурсов документа. В серверной среде безопаснее разрешать только необходимые направления через URLFetcher и политику ОС, а шаблоны и шрифты по возможности держать локально.

Преимущества и недостатки WeasyPrint

Плюсы и минусы

Печатная модель CSS. @page, нумерация, сноски, running elements, закладки и перекрёстные ссылки подходят для документов, где экранная браузерная верстка недостаточна.

Открытая лицензия. BSD 3-Clause не требует подписки, водяных знаков или отдельной коммерческой редакции.

Удобная автоматизация. Есть CLI и полноценный Python API с доступом к страницам, метаданным и URL fetcher.

Продвинутый PDF-выход. Поддерживаются формы, вложения, метаданные, PDF/A, PDF/UA, PDF/X, тегированный PDF и output intent.

Отсутствие обязательного облака. Документы можно генерировать локально или в собственном серверном контуре.

Активное развитие. В 2025–2026 годах выходили крупные релизы с Grid, CMYK/PDF/X, logical properties, исправлениями безопасности и другими изменениями.

Минусы

Нет визуального редактора. Шаблон создаётся кодом; для офисного пользователя это существенно выше по порогу входа.

Не браузер. Современный CSS поддержан не полностью, а JavaScript-ориентированные страницы требуют другого подхода.

Есть ограничения вёрстки. RTL/bidi и writing-mode не поддерживаются полноценно, а Grid имеет перечисленные в документации ограничения.

Производительность требует проектирования. Большие таблицы, массивный DOM, тяжёлые фреймворки и изображения могут сделать рендеринг дорогим.

Недоверенный HTML опасен. Без sandbox, лимитов и фильтрации URL возможны долгие вычисления, чтение локальных файлов и нежелательные сетевые запросы.

Обновление может изменить верстку. Major-релизы следует сопровождать визуальной регрессией, а не обновлять вслепую.

Сравнение с аналогами

Prince наиболее близок по идее специализированной HTML/CSS-печатной вёрстки и ориентирован на профессиональные издательские задачи с коммерческой лицензией. WeasyPrint привлекателен BSD-лицензией и Python API; Prince стоит рассматривать, когда важнее коммерческая поддержка и его собственный набор издательских возможностей.

Chromium Headless предпочтительнее, когда PDF должен повторять реальный браузер с JavaScript и Web Components и современной экранной версткой. WeasyPrint сильнее там, где шаблон изначально проектируется как печатный документ. xhtml2pdf тоже работает из Python, но опирается на иной стек и более ограниченную CSS-модель; миграцию шаблонов между движками нельзя считать механической.

wkhtmltopdf исторически популярен, но его основной репозиторий архивирован с 2023 года, а проект больше не поддерживается. Для нового проекта это серьёзный минус по сравнению с активными релизами WeasyPrint, включая обновления безопасности; сохранять wkhtmltopdf разумно прежде всего ради совместимости уже существующей системы.

Sumatra PDF — не конкурент WeasyPrint по генерации: это Windows-просмотрщик PDF и других документов. Связка логична: WeasyPrint создаёт файл, а PDF-XChange Editor или Sumatra PDF помогают просмотреть результат. Для виртуальной печати из любых Windows-программ ближе doPDF; для универсальных GUI-операций — PDF24 Creator.

Инструкция по установке

Linux: виртуальное окружение

Шаг 1. Проверьте Python 3.10+ и Pango 1.44+; системные библиотеки установите штатным менеджером пакетов дистрибутива.

Шаг 2. Создайте окружение командой python3 -m venv venv, активируйте его и выполните pip install weasyprint.

Шаг 3. Запустите weasyprint —info. Если зависимости определились, зафиксируйте версию пакета в requirements или lock-файле.

macOS

Шаг 1. При установленном Homebrew выполните brew install weasyprint — это рекомендованный простой маршрут.

Шаг 2. Запустите weasyprint —info. При ошибке нативной библиотеки сверяйте путь Homebrew с рекомендацией по DYLD_FALLBACK_LIBRARY_PATH.

Windows: готовый executable

Шаг 1. Получите executable из последнего официального релиза WeasyPrint.

Шаг 2. Проверьте версию. Если защитное ПО сработало, перепроверьте источник и файл, не отключая защиту ради запуска.

Windows: Python-библиотека

Шаг 1. Установите Python через Python Install Manager и MSYS2, затем в UCRT64 добавьте mingw-w64-ucrt-x86_64-pango.

Шаг 2. Создайте venv и установите пакет pip install weasyprint.

Шаг 3. Проверьте weasyprint —info; при ошибке DLL сопоставьте WEASYPRINT_DLL_DIRECTORIES с каталогом MSYS2 UCRT64.

Первый запуск и удаление

Первый тест — weasyprint input.html output.pdf. Для относительных URL источник должен иметь корректную базу либо её задают через base URL. Предупреждения о неизвестных CSS-свойствах и недоступных ресурсах нельзя игнорировать: сначала устраните их, затем открывайте PDF и проверяйте пагинацию.

Пакет, установленный через pip, удаляется командой pip uninstall weasyprint. Изолированный venv можно удалить целиком после сохранения lock/requirements и нужных исходников. Системные Pango/MSYS2/Homebrew-компоненты удаляйте только если они не используются другими приложениями; готовый Windows executable удаляется как обычный файл.

Практические кейсы

Счёт или акт из серверного шаблона

Цель. Генерировать счёт из данных заказа. Подготовка. Версионировать HTML, print CSS, шрифты и изображения. Шаги. Подставить данные на сервере, передать HTML с корректным base_url и записать PDF. Проверка. Сверить сумму, перенос строк, логотип и последнюю страницу. Ограничение. Недоверенные URL и HTML должны проходить изолированные URL fetcher и процесс рендеринга.

Многостраничный отчёт с оглавлением

Цель. Собрать отчёт с колонтитулами и оглавлением. Подготовка. Настроить @page, заголовки, named strings и cross-references. Шаги. Сформировать семантический HTML и вызвать рендеринг. Проверка. Сопоставить номера в оглавлении с фактическими страницами и осмотреть разрывы таблиц. Ограничение. Сложные многостраничные таблицы могут быть медленными.

Архивный PDF/A

Цель. Получить архивный PDF/A. Подготовка. Выбрать подходящий профиль, шрифты и метаданные. Шаги. Задать pdf_variant и сгенерировать документ. Проверка. Прогнать файл внешним валидатором PDF/A и открыть в независимом просмотрщике. Ограничение. Сам факт выбора варианта в WeasyPrint не гарантирует соответствие стандарту.

Доступный PDF/UA

Цель. Сформировать PDF/UA. Подготовка. Сделать HTML семантическим: порядок DOM, заголовки, язык, alt-тексты и подписи. Шаги. Выбрать PDF/UA-1 или PDF/UA-2 и рендерить с тегами. Проверка. Использовать валидатор и, при возможности, screen reader. Ограничение. Движок не исправляет плохую семантику исходного HTML автоматически.

Factur-X/ZUGFeRD

Цель. Выпустить Factur-X/ZUGFeRD. Подготовка. Сформировать корректные RDF-метаданные и XML счёта. Шаги. Создать PDF/A-3b и вложить требуемые машинно читаемые данные. Проверка. Валидировать и PDF/A, и профиль электронного счёта. Ограничение. WeasyPrint отвечает за PDF-сборку, но не за бухгалтерскую корректность XML.

Контроль перед сохранением и передачей

Проверка 1. Убедитесь, что в логе нет неожиданных предупреждений о CSS и ресурсах.

Проверка 2. Осмотрите первую, последнюю и самую сложную страницу; отдельно проверьте разрывы и колонтитулы.

Проверка 3. Откройте PDF в просмотрщике адресата и проверьте ссылки, закладки, вложения или формы, если они используются.

Проверка 4. Для PDF/A, PDF/UA и Factur-X используйте внешний валидатор; визуального просмотра недостаточно.

Проверка 5. Сравните размер файла и качество изображений после изменения optimize_images, quality или DPI.

Проверка 6. Сохраните версию WeasyPrint, lock-файл и исходный шаблон, чтобы результат можно было воспроизвести.

Часто задаваемые вопросы

Можно ли использовать WeasyPrint без Python-кода?

Да. CLI принимает HTML или URL и имя выходного PDF, поэтому собственный Python-скрипт для единичного преобразования не обязателен. Python остаётся частью среды, если используется пакетный вариант установки.

Запускает ли WeasyPrint JavaScript на веб-странице?

Нет полноценного браузерного JavaScript-исполнения. Если страница собирается клиентским JS, сначала получите конечный HTML другим способом либо используйте Chromium Headless.

Можно ли сделать PDF/A или PDF/UA одной опцией?

Опция выбирает PDF/A или PDF/UA-профиль, но не гарантирует валидность исходных данных. Семантика HTML, шрифты, цвета, изображения и метаданные должны соответствовать выбранному стандарту; итог проверяется внешним валидатором.

Подходит ли WeasyPrint для арабского или иврита?

Полноценная поддержка right-to-left и bidirectional text в текущем списке ограничений отсутствует. Для критичных арабских или ивритских документов макет нужно проверять на реальном тексте и при необходимости выбирать другой движок рендеринга.

Что делать, если после обновления «поехала» верстка?

Major-релизы могут менять рендеринг без изменения API. Сравните changelog, воспроизведите различие на минимальном шаблоне и сверяйте новую версию с эталонными PDF; временно зафиксированная прежняя версия допустима только с учётом рисков безопасности.

Безопасно ли давать пользователям поле для собственного HTML?

Только при изоляции. Недоверенные HTML/CSS могут инициировать сетевые и file:// обращения, тяжёлый рендеринг и большие файлы. Используйте непривилегированный процесс или контейнер, лимиты ресурсов, минимальные разрешённые протоколы и собственный URL fetcher; для такой модели особенно важна 70.0 с актуальным исправлением безопасности.

Вывод

WeasyPrint 70.0 подходит проектам, где PDF автоматически собирается из контролируемого HTML/CSS и нужны печатные функции: @page, сноски, колонтитулы, оглавления, ссылки, вложения, формы и стандартизованные PDF-профили. Особенно логичен выбор для Python-бэкенда и воспроизводимых документных шаблонов.

Продукт не подходит как визуальный редактор, OCR, средство ручных аннотаций или конвертер существующего PDF. Для динамичной JavaScript-страницы разумнее Chromium Headless, для коммерческой издательской системы можно оценить Prince, а для ручной работы с PDF — Adobe Acrobat Pro или LibreOffice Writer в тех сценариях, где его PDF-возможностей достаточно.

Успешное внедрение требует воспринимать WeasyPrint как компонент сборки: фиксировать версию и зависимости, хранить исходный HTML/CSS, контролировать URL-доступ и сравнивать визуальный результат после major-релизов. При такой дисциплине сильная печатная CSS-модель и открытая лицензия дают предсказуемый конвейер без облачной привязки.