firecrawl-py

library4.21.0pypypi✓ verified 47d ago

Web scraping API for LLMs — converts any website to clean markdown. Current version is 4.21.0 (Mar 2026). Two separate PyPI packages: firecrawl-py (official SDK) and firecrawl (different package). Class renamed from FirecrawlApp to Firecrawl in v2. Method names changed: scrape_url() → scrape(), crawl_url() → crawl(). Extreme API churn — 0.x to 4.x in one year.

llm-agents http-networking data

pip install firecrawl-py

github ↗package ↗homepage ↗docs ↗

Install & Compatibility

Where this runs

tested against v4.28.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.950 runs

installs and imports cleanly · install 0.0s · import 2.009s · 46.4MB

glibc

py 3.10–3.950 runs

installs and imports cleanly · install 7.1s · import 1.805s · 48MB

47MB installed

● package 47MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

FirecrawlApp

✓ from firecrawl import FirecrawlApp

✗ from firecrawl import Firecrawl

ScrapeOptions

✓ from firecrawl import V1ScrapeOptions

✗ from firecrawl.types import ScrapeOptions

v2+ API. scrape() for single URLs, crawl() blocks until done, start_crawl() for async.

from firecrawl import Firecrawl from firecrawl.types import ScrapeOptions import os # API key from env or direct firecrawl = Firecrawl(api_key=os.environ.get('FIRECRAWL_API_KEY')) # Scrape single URL → markdown result = firecrawl.scrape( 'https://docs.firecrawl.dev', formats=['markdown', 'html'] ) print(result.markdown[:500]) print(result.metadata.title) # Crawl entire site (blocking, auto-polls) crawl = firecrawl.crawl( 'https://docs.firecrawl.dev', limit=50, scrape_options=ScrapeOptions(formats=['markdown']), poll_interval=5 ) for doc in crawl.data: print(doc.metadata.source_url, len(doc.markdown or '')) # Async crawl (non-blocking) job = firecrawl.start_crawl( 'https://docs.firecrawl.dev', limit=50 ) status = firecrawl.get_crawl_status(job.id)

Debug

Known issues

breakingFirecrawlApp class renamed to Firecrawl in v2.0. from firecrawl import FirecrawlApp raises ImportError. All v1 tutorial code is broken.

fix

Replace: from firecrawl import FirecrawlApp → from firecrawl import Firecrawl. Replace: FirecrawlApp(api_key=...) → Firecrawl(api_key=...)

affects: >= 2.0

breakingMethod names changed in v2: scrape_url() → scrape(), crawl_url() → crawl(), check_crawl_status() → get_crawl_status(). All old method calls raise AttributeError.

fix

Update all method calls: app.scrape_url(url) → firecrawl.scrape(url, formats=[...]), app.crawl_url(url, params) → firecrawl.crawl(url, ...)

affects: >= 2.0

breakingExtreme version churn: 0.x → 1.x → 2.x → 3.x → 4.x all within ~1 year. Each major version has breaking API changes. Code from tutorials more than a few months old is likely broken.

fix

Pin exact version in requirements.txt. Check GitHub releases before upgrading.

affects: all

gotchapip install firecrawl installs a DIFFERENT package — not the official Firecrawl SDK. The correct install is pip install firecrawl-py.

fix

Always use pip install firecrawl-py. The import is still from firecrawl import Firecrawl.

affects: all

gotchaAPI response fields use camelCase in the Firecrawl REST API (sourceURL, ogTitle) but the Python SDK auto-converts to snake_case (source_url, og_title). Raw API response and SDK response field names differ.

fix

Use SDK snake_case field names: result.metadata.source_url not result.metadata.sourceURL.

affects: >= 2.0

breakingThe Firecrawl client requires an API key for initialization. If the `FIRECRAWL_API_KEY` environment variable is not set, or the `api_key` argument is not explicitly passed to the `Firecrawl` constructor, a `ValueError: No API key provided` will be raised.

fix

Ensure the `FIRECRAWL_API_KEY` environment variable is set with your Firecrawl API key, or pass the API key directly when initializing the client: `firecrawl = Firecrawl(api_key='YOUR_API_KEY')`.

affects: all

breakingThe Firecrawl SDK requires an API key for initialization. If not provided directly, it expects the `FIRECRAWL_API_KEY` environment variable to be set. Missing or empty API key will raise a `ValueError`.

fix

Ensure the `FIRECRAWL_API_KEY` environment variable is set with a valid API key, or pass the `api_key` argument directly to the `Firecrawl` constructor: `Firecrawl(api_key='YOUR_API_KEY')`.

affects: all

Upgrade

Version history

4.28.2latest on PyPI

Audit

Dependencies

requestsrequiredRequired. Installed automatically.

pydanticrequiredRequired. Installed automatically.

aiohttprequiredRequired for async support. Installed automatically.

websocketsrequiredRequired for crawl watching. Installed automatically.

Agent activity

19 hits · last 30 days