Documentation • PyPI • Changelog • News • Chat

WebSite2PDF

Render web pages and local HTML files to PDF, from Python or from the shell. Fully typed, async-capable, and driven by headless Chromium through Playwright.

from website2pdf import Client

with Client() as client:
    client.convert("https://example.com", "example.pdf")

Installation

pip install website2pdf

Then download the browser Playwright manages. This step is required, the library has nothing to render with until it has run:

playwright install chromium

For the command line, install the extra as well:

pip install "website2pdf[cli]"

Python 3.10 or newer. The browser download is roughly 150 MB and is shared by every project on the machine.

Usage

One page

from website2pdf import Client

with Client() as client:
    # Get the bytes back...
    data = client.convert("https://example.com")

    # ...or write a file, and get its path.
    path = client.convert("https://example.com", "report.pdf")

    # Name the file after the page title.
    path = client.convert("https://example.com", "{title}.pdf")

Local files work the same way, as a path or a file:// URL:

from pathlib import Path

client.convert(Path("invoice.html"), "invoice.pdf")

Many pages

with Client() as client:
    paths = client.convert_many(
        ["https://example.com", "https://example.org"],
        "out/",
    )

Pages that share a title do not overwrite each other: the second file becomes Title (2).pdf.

Concurrently

AsyncClient renders several pages at once in independent browser contexts, sharing a single browser process.

import asyncio

from website2pdf import AsyncClient


async def main() -> None:
    async with AsyncClient(concurrency=8) as client:
        await client.convert_many(urls, "out/")


asyncio.run(main())

Options

Three immutable option objects, each covering one concern. Set them on the client as defaults, override them per call.

from website2pdf import BrowserOptions, Client, Margin, PdfOptions, RenderOptions

with Client(
    pdf_options=PdfOptions(paper_format="A4", margin=Margin.uniform("1cm")),
    render_options=RenderOptions(wait_until="networkidle"),
    browser_options=BrowserOptions(user_agent="my-crawler/1.0"),
) as client:
    client.convert("https://example.com", "default.pdf")
    client.convert(
        "https://example.com",
        "landscape.pdf",
        pdf_options=PdfOptions(landscape=True, print_background=False),
    )

A page that fills itself in after loading needs an explicit wait:

client.convert(
    "https://example.com",
    "chart.pdf",
    render_options=RenderOptions(wait_for_selector="#chart-ready"),
)

Chromium prints with print media by default. To reproduce what a visitor sees on screen:

render_options = RenderOptions(emulate_media="screen")

The full reference lives in the options documentation.

Command line

website2pdf https://example.com -o report.pdf
website2pdf https://example.com https://example.org -o out/
website2pdf https://example.com --format A5 --landscape --margin 1cm
website2pdf https://example.com -o - > report.pdf          # straight to stdout
cat urls.txt | website2pdf - -o out/ --concurrency 8        # one URL per line

website2pdf --help lists every option.

Errors

Everything the library raises derives from WebSite2PDFError, so one except covers it:

from website2pdf import BrowserNotInstalledError, NavigationError, WebSite2PDFError

try:
    client.convert(url, "out.pdf")
except BrowserNotInstalledError:
    ...  # tells you to run `playwright install chromium`
except NavigationError:
    ...  # the page did not load in time
except WebSite2PDFError:
    ...  # anything else from this library

Notes

Client runs Playwright's synchronous driver on the calling thread, which means asyncio.run() cannot start on that thread while a client is open. In an asyncio program, use AsyncClient. Several Client instances on one thread are fine, they share one reference-counted driver.

PDF rendering is Chromium-only: it is the only engine that exposes a print-to-PDF command.

Migrating from 0.x

Version 1.0 is a rewrite with a new import name and a new API. Nothing from 0.x carries over unchanged.

Client is now a context manager, and convert() returns bytes when you omit the destination and a Path when you give one, never a union of four types. The migration guide walks through it.

Contributing

See CONTRIBUTING.md. In short:

uv sync --all-extras --all-groups
uv run playwright install chromium
uv run pytest

Licence

MIT.