Skip to main content

cf-browser

Typed async Python SDK for Cloudflare Browser Run (formerly Browser Rendering). Use CFBrowserDirect against Cloudflare's REST API or CFBrowser through the authenticated Worker proxy.

Install

python -m pip install cf-browser

Python 3.10–3.14 is supported (CI also exercises 3.15). The wheel includes a PEP 561 py.typed marker.

Direct mode

from cf_browser import CFBrowserDirect

async with CFBrowserDirect(account_id="...", api_token="...") as browser:
    markdown = await browser.markdown("https://example.com")
    links = await browser.links(
        "https://example.com",
        include_external=False,
        visible_only=True,
    )
    tree = await browser.a11y("https://example.com")

Direct mode has no local cache or proxy rate limit. Browser interaction methods raise NotImplementedError.

Worker mode

from cf_browser import CFBrowser

async with CFBrowser(base_url="https://...workers.dev", api_key="...") as browser:
    png = await browser.screenshot(
        "https://example.com",
        width=1280,
        height=720,
        no_cache=True,
    )
    data = await browser.json_extract(
        "https://example.com/products",
        response_format={
            "type": "json_schema",
            "json_schema": {
                "type": "object",
                "properties": {"products": {"type": "array"}},
            },
        },
    )
    job_id = await browser.crawl("https://example.com", limit=20)
    result = await browser.crawl_wait(job_id, timeout=300, poll_interval=2)
    await browser.delete_crawl(job_id)

schema= remains a compatibility alias for structured extraction and is translated to Cloudflare's current response_format shape.

API

Method Returns Notes
content(url) str Rendered HTML
markdown(url) str Markdown
screenshot(url) bytes PNG; validates viewport bounds
pdf(url) bytes Supported paper format and landscape options
snapshot(url) dict Content, Markdown, screenshot, and optional accessibility tree
scrape(url, selectors) dict {"elements": [...]}
json_extract(url, prompt?, response_format?) Any Prompt and/or JSON schema
links(url) list[dict] Normalized {href, text} items
a11y(url) dict Native accessibility tree
crawl(url) str Job ID
crawl_status(job_id, cursor?, limit?, status?) dict String or integer opaque cursor pagination
crawl_wait(job_id) dict Lightweight polling, then complete records
delete_crawl(job_id) None Cancels the Cloudflare crawl
click, type_text, evaluate, interact, submit_form dict Worker mode and BROWSER binding only

Common page options include cookies, headers, authenticate, wait_for, wait_until, timeout, user_agent, injected tags, and rejected resource types. no_cache controls local Worker caching; for crawls in either mode it maps to upstream cacheTTL=0. Crawls default to render=True and support cache_ttl (0-86400), depth, formats, crawl_purposes, max_age, modified_since, include/exclude patterns, json_options, and rendered request/JavaScript/viewport controls. Static crawls (render=False) reject browser-only options. Cloudflare does not support user_agent for crawl requests.

Typed exceptions include AuthenticationError, RateLimitError, NotFoundError, BrowserUnavailableError, TransportError, and CrawlJobError, all deriving from CFBrowserError. crawl_wait() raises the built-in TimeoutError while a job is still running at the deadline, and its subclass CrawlResultsTimeoutError when the job completed but its result pages could not be fetched in time; malformed upstream pagination raises CFBrowserError with status 502.

API keys and tokens must be visible ASCII (no whitespace or line breaks) and are never included in error messages. The default timeout (320 s Worker, 310 s Direct) covers Cloudflare's longest synchronous action, while connecting is capped at 10 s so unreachable hosts fail fast.

See the project README for deployment and security details.

License

MIT

Metadata

Release files for cf-browser 2.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cf-browser 2.1.0
File Size Uploaded Provenance Actions
cf_browser-2.1.0.tar.gz 36.0 kB With provenance Details for cf_browser-2.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cf-browser 2.1.0
File Interpreter ABI Platform Actions
cf_browser-2.1.0-py3-none-any.whl Python 3 none any Details for cf_browser-2.1.0-py3-none-any.whl

Total release size: 62.1 kB

Release files / cf_browser-2.1.0.tar.gz

Download URL cf_browser-2.1.0.tar.gz
Size 36.0 kB
Tags Source
SHA-256 checksum
How to use checksums
63f7947c70ea46ad5f472dd31788cf0e0aa952224f29ec7b2b90aa18a9bf3369
BLAKE2b-256 checksum
How to use checksums
2517a434de31b7b872d1883c08c90e985236de6dafddf5462171793fed9bc64e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.

Transparency log

Release files / cf_browser-2.1.0-py3-none-any.whl

Download URL cf_browser-2.1.0-py3-none-any.whl
Size 26.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
96a26ba788c74e13198cd2f81e9098304db3e3179b825335801584ad526afdf8
BLAKE2b-256 checksum
How to use checksums
420afed8e3ce417b39aaf3b38394b9df5f98ec80a349b5fcab8cd6504cb055f7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.

Transparency log

Security for cf-browser 2.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for cf_browser-2.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page