IRONSOFTWAREHOME
IRONSUITE所有10的价格为2
联系销售
按公司
加入我们的专家网络

在Python中将HTML转换为PDF

Curtis Chau
Curtis Chau
Updated: 2026年6月29日

IronPDF为Python开发者提供了一条从HTML标记到生产就绪PDF文件的直接路径——不需要中间设计工具，没有专有布局引擎，没有单独的渲染管道。库的ChromePdfRenderer类在底层使用基于Chromium的引擎，因此在Chrome中正确显示的任何HTML将准确地转换为PDF。 本教程演示了每种受支持的转换方法——HTML字符串、本地HTML文件和实时URL——然后涵盖了允许您控制页面大小、边距、页眉、页脚等的渲染选项。

如果您需要C#或VB.NET的工作流程，将HTML转换为PDF的.NET应用程序也有相关教程。

快速入门：在Python中将HTML转为PDF

如何在 Python 中将 HTML 转换为 PDF

IronPDF Python 库将 HTML 页面转换为 PDF 文件
  1. 通过pip安装IronPDF for Python
  2. 使用from ironpdf import *导入库
  3. 实例化ChromePdfRenderer
  4. 调用RenderHtmlAsPdf、RenderUrlAsPdf或RenderHtmlFileAsPdf
  5. 使用pdf.SaveAs("output.pdf")保存结果
目录

入门

如何安装Python上的IronPDF？

IronPDF通过pip分发，这是Python的标准包管理器。 在终端中运行以下命令以安装最新版本：

> pip install ironpdf

要固定特定版本——在CI管道或容器化环境中很有用——附上版本号：

> pip install ironpdf==2024.x.x

请注意: IronPDF for Python建立在IronPDF .NET库之上，需使用.NET 6.0 SDK或更高版本。 在运行任何IronPDF Python代码之前安装SDK。)]

IronPDF首次初始化时，会下载兼容的Chromium二进制文件。 在新机器上下载稍需片刻，但每个环境仅发生一次。 随后的运行启动速度快得多，因为二进制文件被本地缓存。

操作指南和代码示例

您如何在转换之前配置IronPDF？

在首次转换调用之前完成两项设置任务：设置许可证密钥和——可选地——配置日志文件位置。

导入包

每个使用IronPDF的Python文件都需要这一行导入。将其放在文件顶部：

from ironpdf import *
Python

所有IronPDF类——Logger，以及其他类——通过此通配符导入变得可用。

设置许可证密钥

没有许可证密钥，IronPDF会在每个生成的PDF上添加平铺水印。 水印适合开发和测试，但生产部署需要有效密钥。

无许可证密钥生成的PDF包含平铺水印。访问许可页面以获取密钥。

在任何其他IronPDF调用之前设置密钥：

from ironpdf import *

# Set the license key before any PDF operations
License.LicenseKey = "IRONPDF-MYLICENSE-KEY-1EF01"
Python

开始免费试用以接收临时密钥，或购买许可证以供无限制的生产使用。

配置日志输出

IronPDF将诊断输出写入名为Default.log的文件中，该文件位于脚本的工作目录中。 要将日志记录重定向到不同路径或捕获更多细节以进行调试，在第一次转换前设置Logger属性：

from ironpdf import *

# Configure logging before running any conversions
Logger.EnableDebugging = True
Logger.LogFilePath = "ironpdf-debug.log"
Logger.LoggingMode = Logger.LoggingModes.All
Python
请注意: Logger.LogFilePath必须在第一次PDF转换调用之前设置。 之后做出的更改对当前会话不起作用。

详细日志在诊断特定HTML页面未按预期渲染时最有用——它们捕获网络请求、CSS加载事件和JavaScript执行时间。

如何将HTML字符串转换为PDF？

转换内存中的HTML字符串是最直接的方法，并且在HTML是通过编程生成时效果良好——例如，从Jinja2模板或数据库驱动的报告生成。

基本HTML字符串转换

实例化SaveAs：

from ironpdf import *

renderer = ChromePdfRenderer()

# Convert an HTML string to a PDF document
pdf = renderer.RenderHtmlAsPdf("<h1>Hello from IronPDF!</h1><p>Generated in Python.</p>")

pdf.SaveAs("hello.pdf")
Python
从简单 HTML 字符串渲染的 PDF，显示一个标题和一个段落

RenderHtmlAsPdf精确处理HTML，就像Chrome会做的，包括CSS和JavaScript。

ChromePdfRenderer以现代浏览器的方式处理HTML、CSS和JavaScript。 在Chrome中正确渲染的任何内容将生成准确的PDF。

具有外部资产的HTML字符串

当HTML字符串引用本地资源（样式表、图像、脚本）时，将目录路径作为第二个参数传递给RenderHtmlAsPdf。 IronPDF将此路径用作基础URL，以解析相对引用：

from ironpdf import *

html_content = """
<html>
  <head>
    <title>Styled Report</title>
    <link rel='stylesheet' href='assets/style.css'>
  </head>
  <body>
    <h1>Monthly Report</h1>
    <img src='assets/logo.png' alt='Company logo'>
    <p>Data as of Q1 2024.</p>
  </body>
</html>
"""

renderer = ChromePdfRenderer()

# The second argument sets the base path for resolving relative asset URLs
pdf = renderer.RenderHtmlAsPdf(html_content, "./")

pdf.SaveAs("styled-report.pdf")
Python
从引用外部 CSS 和图像资源的 HTML 字符串生成的 PDF 输出

当您提供基路径给RenderHtmlAsPdf时，外部CSS和图像正确加载。

基路径可以指向任何本地目录或网络共享。 子目录中的资产相对于它解析。 有关复杂HTML字符串的更多模式，请参见HTML字符串到PDF代码示例。

如何将URL转换为PDF？

RenderUrlAsPdf方法获取一个实时URL，等待页面完全加载（包括任何JavaScript驱动的内容），并将渲染结果转换为PDF。 这使其适用于捕捉仪表板、报告或任何视觉状态取决于JavaScript执行的页面。

from ironpdf import *

renderer = ChromePdfRenderer()

# Fetch and convert a live web page to PDF
pdf = renderer.RenderUrlAsPdf("https://en.wikipedia.org/wiki/Portable_Document_Format")

pdf.SaveAs("wikipedia-pdf.pdf")
Python
使用 IronPDF 的 RenderUrlAsPdf 方法从维基百科文章 URL 生成的 PDF

IronPDF获取实时URL并渲染整页——包括JavaScript——再生成PDF。

提示: 对于需要身份验证的页面，在调用ChromePdfRenderer实例上设置cookie或HTTP请求头。 详情请参见HTTP登录凭据指南。

当目标页面加载异步内容时，IronPDF会等待Chromium渲染引擎发出文档完全绘制的信号。 对于具有大量JavaScript或延迟网络请求的页面，可以考虑调整ChromePdfRenderOptions上的属性（在下面的渲染选项部分有介绍）。 URL到PDF代码示例显示了其他配置模式。

您如何将HTML文件转换为PDF？

RenderHtmlFileAsPdf接受本地HTML文件的路径并直接转换。 HTML中的相对路径——到CSS文件、图像或JavaScript——会根据HTML文件的目录自动解析，因此不需要基路径参数。

from ironpdf import *

renderer = ChromePdfRenderer()

# Convert a local HTML file (and its linked CSS/JS) to PDF
pdf = renderer.RenderHtmlFileAsPdf("invoices/TestInvoice1.html")

pdf.SaveAs("invoice.pdf")
Python

此方法特别适用于服务器端文档生成，其中HTML模板已被写入磁盘——在使用Django或Flask将Jinja2模板渲染为文件，再转换为PDF以便下载时常见的模式。

IronPDF相对于HTML文件位置解析任何<img>标签，因此链接的样式表、嵌入的字体和图像在PDF中显示与在浏览器中一样。 该过程反映了RenderHtmlAsPdf如何处理内联资源，区别在于不需要提供显式的基路径。

您如何控制PDF渲染选项？

ChromePdfRenderer（或直接传递给任何渲染方法）的配置对象，用于控制页面布局、边距、纸张尺寸和其他输出特性。 在转换之前设置选项是定制PDF输出的标准方式。

纸张尺寸和方向

from ironpdf import *

renderer = ChromePdfRenderer()

# Configure page layout before rendering
renderer.RenderingOptions.PaperSize = PdfPaperSize.A4
renderer.RenderingOptions.PaperOrientation = PdfPaperOrientation.Landscape
renderer.RenderingOptions.MarginTop = 20
renderer.RenderingOptions.MarginBottom = 20
renderer.RenderingOptions.MarginLeft = 15
renderer.RenderingOptions.MarginRight = 15

pdf = renderer.RenderHtmlAsPdf("<h1>Landscape Report</h1><p>Content here.</p>")
pdf.SaveAs("landscape-a4.pdf")
Python

边距以毫米表示。 CustomPaperHeight定义的任意尺寸。

自定义纸张尺寸

当标准纸张尺寸不符合输出要求时——例如，收据或标签打印格式——明确定义宽度和高度：

from ironpdf import *

renderer = ChromePdfRenderer()

# Set a custom paper size (in millimetres)
renderer.RenderingOptions.PaperSize = PdfPaperSize.Custom
renderer.RenderingOptions.CustomPaperWidth = 80   # 80 mm receipt roll width
renderer.RenderingOptions.CustomPaperHeight = 200

pdf = renderer.RenderHtmlAsPdf("<h2>Receipt</h2><p>Total: $12.50</p>")
pdf.SaveAs("receipt.pdf")
Python
重要: 自定义纸张尺寸对于热敏收据打印机和标签格式（如4×6英寸的运输标签）特别有用。

启用JavaScript执行

默认情况下，IronPDF在渲染期间执行JavaScript。 如果页面依赖于JavaScript生成可见内容——图表、数据表、动态表单值——这种行为意味着渲染的PDF反映了最终的DOM状态。 要在不必要的页面上禁用JavaScript：

from ironpdf import *

renderer = ChromePdfRenderer()

# Disable JavaScript for static HTML pages
renderer.RenderingOptions.EnableJavaScript = False

pdf = renderer.RenderHtmlAsPdf("<p>Static content only.</p>")
pdf.SaveAs("static.pdf")
Python

禁用JavaScript可减少简单、静态HTML文档的渲染时间。

有关更多渲染配置详情，请参见PDF生成设置和自定义纸张尺寸示例。

如何添加自定义页眉和页脚？

IronPDF中的页眉和页脚通过附加到渲染器的TextHeaderFooter对象应用。 HtmlHeaderFooter为您提供完整的HTML和CSS控制——非常适合带有徽标的品牌信头。 TextHeaderFooter更简单，并涵盖大多数基于文本的需求，包括动态页码。

基于文本的页眉和页脚

from ironpdf import *

renderer = ChromePdfRenderer()

# Add a text header with the document title
renderer.RenderingOptions.TextHeader = TextHeaderFooter()
renderer.RenderingOptions.TextHeader.CenterText = "Quarterly Report — Q1 2024"
renderer.RenderingOptions.TextHeader.DrawDividerLine = True
renderer.RenderingOptions.TextHeader.FontSize = 10

# Add a footer with page numbers
renderer.RenderingOptions.TextFooter = TextHeaderFooter()
renderer.RenderingOptions.TextFooter.RightText = "Page {page} of {total-pages}"
renderer.RenderingOptions.TextFooter.FontSize = 9
renderer.RenderingOptions.TextFooter.DrawDividerLine = True

html = "<h1>Executive Summary</h1><p>Revenue increased 12% year-over-year.</p>"
pdf = renderer.RenderHtmlAsPdf(html)
pdf.SaveAs("report-with-footer.pdf")
Python

{total-pages}占位符在渲染时替换为正确的值。 其他可用占位符包括{url}。

带有徽标的HTML页眉

当需要带有公司徽标、彩色条带或格式化地址块的品牌页眉时，使用HtmlHeaderFooter代替：

from ironpdf import *

renderer = ChromePdfRenderer()

header_html = """
<div style="font-family: Arial, sans-serif; border-bottom: 2px solid #003366; padding: 8px 0;">
  <img src='assets/logo.png' style='height: 40px; float: left;' alt='Company logo'>
  <span style='float: right; font-size: 11px; color: #666;'>Confidential</span>
  <div style='clear:both;'></div>
</div>
"""

renderer.RenderingOptions.HtmlHeader = HtmlHeaderFooter()
renderer.RenderingOptions.HtmlHeader.HtmlFragment = header_html
renderer.RenderingOptions.HtmlHeader.BaseUrl = "./"

html_body = "<h1>Project Status Update</h1><p>All milestones on track.</p>"
pdf = renderer.RenderHtmlAsPdf(html_body, "./")
pdf.SaveAs("branded-report.pdf")
Python
请注意: 将HtmlHeaderFooter上，与文档主体使用的基路径相同。 这确保了页眉HTML中引用的图片和样式表可以正确解析。

页眉和页脚出现在生成的PDF的每一页上，包括多页文档。 有关在页脚中包含页面级元数据的工作示例，请参见HTML页眉和页脚代码示例。

页眉和页脚的边距调整

添加页眉或页脚时，请增加相应的边距以防内容与页面主体重叠：

from ironpdf import *

renderer = ChromePdfRenderer()

renderer.RenderingOptions.MarginTop = 30     # Make room for header
renderer.RenderingOptions.MarginBottom = 20  # Make room for footer

renderer.RenderingOptions.TextHeader = TextHeaderFooter()
renderer.RenderingOptions.TextHeader.CenterText = "Internal Use Only"

renderer.RenderingOptions.TextFooter = TextHeaderFooter()
renderer.RenderingOptions.TextFooter.CenterText = "Page {page} of {total-pages}"

pdf = renderer.RenderHtmlAsPdf("<h1>Internal Document</h1><p>Body content.</p>")
pdf.SaveAs("margined-report.pdf")
Python

对于布局关键文档，将边距调整与PaperSize设置结合，以使输出完全符合打印规范。 附加的布局控件——如IronSoftwareSystemDrawingColor背景填充和CSS @page规则——在自定义边距示例中详细介绍。

下一步是什么？

本教程涵盖了三个核心HTML到PDF的转换方法及其输出控制的渲染选项。 以下指南是在此基础上构建的，并涵盖更专业的任务：

  • PDF生成设置——深入探讨ChromePdfRenderOptions：DPI、背景渲染、CSS媒体类型、JavaScript等待策略，打印模式和屏幕模式。
  • HTML页眉和页脚——带有徽标、页码、日期和多栏布局的品牌页眉和页脚模板。
  • 自定义边距和纸张尺寸——微调页面几何形状，以获得打印就绪的输出和非标准格式。
  • 向PDF添加水印——将文本或图像水印印在现有或新生成的PDF上。
  • 从PDF中提取文本——以编程方式读取生成或现有PDF的文本内容。

开始免费的30天试用，在评估期间生成无限制、无水印的PDF。 准备好生产时，请查看许可选项以进行团队和企业部署。

常见问题解答

我如何在Python中将HTML字符串转换为PDF？

实例化ChromePdfRenderer，然后调用renderer.RenderHtmlAsPdf(html_string)。该方法接受任何有效的HTML，包括内联CSS和JavaScript。用pdf.SaveAs("output.pdf")保存返回的PdfDocument。

如何安装 IronPDF for Python？

从终端运行pip install ironpdf。IronPDF for Python需要.NET 6.0 SDK或更高版本，在首次使用前必须单独安装。

IronPDF是否可以在Python中将实时URL转换为PDF？

可以。使用renderer.RenderUrlAsPdf("https://example.com")。IronPDF使用Chromium引擎获取页面，等待JavaScript完成执行，然后从完全渲染的DOM生成PDF。

我如何将本地HTML文件转换为PDF？

调用renderer.RenderHtmlFileAsPdf("path/to/file.html")。IronPDF自动将样式表、图像、脚本等所有相对资产路径解析为相对于HTML文件目录的路径。

如何移除IronPDF生成的PDF上的水印？

在任何PDF操作之前，使用License.LicenseKey = "YOUR-KEY"设置一个有效的许可证密钥。如果没有密钥，IronPDF将添加适合开发但不适合生产使用的平铺水印。

IronPDF为Python提供了哪些渲染选项？

在renderer.RenderingOptions上设置的属性控制纸张大小（PaperSize）、方向（PaperOrientation）、边距（MarginTop、MarginLeft等）、自定义尺寸（CustomPaperWidth、CustomPaperHeight）、JavaScript执行（EnableJavaScript）等等。

如何在Python的IronPDF中为PDF添加页码？

将TextHeaderFooter分配给renderer.RenderingOptions.TextFooter，并在文本属性之一如RightText或CenterText中包含占位符{page}或{total-pages}。

我能否为生成的PDF的每页添加品牌标志页眉？

可以。使用带<img>标签的HTML片段创建HtmlHeaderFooter。分配给renderer.RenderingOptions.HtmlHeader并设置BaseUrl以正确解析图像路径。

IronPDF在Python中是否支持自定义纸张尺寸？

可以。将renderer.RenderingOptions.PaperSize设置为PdfPaperSize.Custom，然后分配CustomPaperWidth和CustomPaperHeight以毫米为单位定义任意页面尺寸。

IronPDF for Python需要哪个.NET版本？

IronPDF for Python需要.NET 6.0 SDK或更高版本。该SDK可从Microsoft .NET下载页面免费获得，并且必须在pip安装或运行IronPDF之前安装。

Curtis Chau
Curtis Chau
技术作家

Curtis Chau 拥有卡尔顿大学的计算机科学学士学位，专注于前端开发，精通 Node.js、TypeScript、JavaScript 和 React。他热衷于打造直观且美观的用户界面，喜欢使用现代框架并创建结构良好、视觉吸引力强的手册。

...
阅读更多

准备开始了吗？

版本:2026.9刚刚发布

免费 pip 安装

免费获取

30天试用密钥 即刻获取。

bullet_checked无需信用卡或创建账户
bullet_test在生产环境中测试
且无水印
bullet_calendar30天完全
功能性产品
bullet_support试用期间提供
24/5技术支持
立即获取您的免费30 天试用密钥。
无需信用卡或创建账户
Python 模块下载 PDF
using pip 安装

版本: 2026.9

> pip install ironpdf
https://pypi.org/project/IronPdf/
  1. 下载 并安装 Python 3.7+。
  2. 如果尚未安装，请从 pypi.org 安装 pip。
  3. 在终端中执行上述命令。
Python PDF 模块
下载 模块

版本: 2026.9

手动安装到您的项目中

  1. 下载软件包
  2. 在终端中运行此命令 
    pip install ironpdf-2026.9-py37-none-win_amd64.whi

$999 起

Key in blue circle

立即获取免费的 30 天试用版密钥。

Your trial license will be sent to your email address

无任何限制。100% 解锁。无需信用卡。

OR
bullet_checked无需信用卡或创建账户无任何限制。100% 解锁。无需信用卡。
  • Logo Aetna
  • Logo NASA
  • Logo GE
  • Logo Porsche
  • Logo USDA
  • Logo Qatar
Join Millions of Engineers who’ve tried Iron Suite
预约您的免费现场演示
Booking Badge

深受全球数百万工程师信赖

Iron Software 的客户徽标
获取您的无义务咨询
填写下面的表格或通过sales@ironsoftware.com
您的资料将始终保密。
深受全球数百万工程师信赖
Iron Software 的客户徽标
立即获取您的免费30 天试用密钥。
无需信用卡或创建账户
Python 模块下载 PDF
using pip 安装

版本: 2026.9

> pip install ironpdf
https://pypi.org/project/IronPdf/
  1. 下载 并安装 Python 3.7+。
  2. 如果尚未安装，请从 pypi.org 安装 pip。
  3. 在终端中执行上述命令。
Python PDF 模块
下载 模块

版本: 2026.9

手动安装到您的项目中

  1. 下载软件包
  2. 在终端中运行此命令 
    pip install ironpdf-2026.9-py37-none-win_amd64.whi

$999 起