python-pdfkit：HTML 转 PDF，几行代码的事

python-pdfkit 在 GitHub 上拿到了 2,042 Star。

一个 Python 3 对 wkhtmltopdf 的封装库，把 HTML 转成 PDF。不折腾命令行，不手写子进程管理，直接调函数。

1、这个工具干了什么

把 HTML 变成 PDF，仅此而已。

底层依赖 wkhtmltopdf，python-pdfkit 做的事是把命令行调用包装成 Python 接口。你不需要自己拼参数、管理临时文件、处理进程输出，这些脏活它全兜了。

2、怎么用

三种输入方式，覆盖日常场景：

import pdfkit

pdfkit.from_url('http://google.com', 'out.pdf')
pdfkit.from_file('test.html', 'out.pdf')
pdfkit.from_string('Hello!', 'out.pdf')

from_url 适合抓网页、生成报告快照。from_file 支持传列表，多个 HTML 文件合并成一个 PDF。from_string 跟后端模板渲染搭配最顺手，页面渲染完直接导出。

不指定输出路径的话，PDF 数据直接返回，方便进一步处理：

pdf = pdfkit.from_url('http://google.com')

选项透传做得很全。wkhtmltopdf 的上百个参数全部通过 options 字典传入，去掉 -- 前缀就行：

options = {
    'page-size': 'Letter',
    'margin-top': '0.75in',
    'margin-right': '0.75in',
    'encoding': 'UTF-8',
    'custom-header': [('Accept-Encoding', 'gzip')],
    'no-outline': None
}
pdfkit.from_url('http://google.com', 'out.pdf', options=options)

还有一个容易忽略的细节：HTML 里直接写 meta 标签也能传参数。

<meta name="pdfkit-page-size" content="Legal"/>
<meta name="pdfkit-orientation" content="Landscape"/>

pdfkit 会自动解析并转成命令行参数，不需要在代码里再写一遍 options。

3、稍微进阶的用法

目录和封面是两个独立参数，不塞在 options 里：

toc = {'xsl-style-sheet': 'toc.xsl'}
cover = 'cover.html'
pdfkit.from_file('file.html', options=options, toc=toc, cover=cover)

外部 CSS 也支持，单文件或列表都行：

pdfkit.from_file('file.html', options=options, css=['a.css', 'b.css'])

wkhtmltopdf 不在系统 PATH 里时，手动指一下路径：

config = pdfkit.configuration(wkhtmltopdf='/opt/bin/wkhtmltopdf')
pdfkit.from_string(html_string, output_file, configuration=config)

4、几个坑

这个库已经标记为 deprecated，原因是 wkhtmltopdf 项目本身处于停滞状态。如果你的场景对 PDF 渲染精度要求不高、WebKit 引擎够用，继续用没问题。新项目或者需要长期维护的生产环境，建议先评估替代方案。

Ubuntu/Debian 源里的 wkhtmltopdf 是阉割版，编译时没开 QT 补丁，目录、页眉页脚这些功能都用不了。要完整功能得去 wkhtmltopdf 官网下静态二进制包。

另一个常见坑是 IOError: 'No wkhtmltopdf executable found'，系统 PATH 里找不到 wkhtmltopdf。Linux 上跑 which wkhtmltopdf，Windows 上跑 where wkhtmltopdf，确认路径后再用 configuration 指定。

5、适合什么人用

• 用 Django/Flask 做报表系统、需要「导出 PDF」功能的后端开发者
• 项目里已经有 wkhtmltopdf 依赖、想简化调用代码的场景
• 需要把服务端渲染的 HTML 页面快速转成 PDF 文件的小工具

报表系统、需要「导出 PDF」功能的后端开发者

• 项目里已经有 wkhtmltopdf 依赖、想简化调用代码的场景
• 需要把服务端渲染的 HTML 页面快速转成 PDF 文件的小工具