Install & Compatibility
Where this runs
tested against v0.1.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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 34.9MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 9.7s · import 1.064s · 359MB
203MB installed
● package 203MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Fetcher
✓ from scrapling.fetchers import Fetcher
✗ from scrapling.defaults import Fetcher
The `scrapling.defaults` path was used in older examples but `scrapling.fetchers` is the current and recommended path for fetcher classes.
StealthyFetcher
✓ from scrapling.fetchers import StealthyFetcher
Spider
✓ from scrapling.spiders import Spider
Response
✓ from scrapling.spiders import Response
FetcherSession
✓ from scrapling.fetchers import FetcherSession
This quickstart demonstrates basic HTTP fetching with `Fetcher` to extract data using CSS selectors. It also includes a minimal example of Scrapling's `Spider` framework for structured, asynchronous crawling, similar to Scrapy.
from scrapling.fetchers import Fetcher
from scrapling.spiders import Spider, Response
import asyncio
# --- Basic HTTP Fetching ---
print("\n--- Basic HTTP Fetching ---")
page = Fetcher.get('https://quotes.toscrape.com/')
quotes = page.css('.quote .text::text').getall()
authors = page.css('.quote .author::text').getall()
print(f"First quote: {quotes[0]}\nAuthor: {authors[0]}")
# --- Basic Spider Framework ---
print("\n--- Basic Spider Framework ---")
class QuotesSpider(Spider):
name = "quotes_spider"
start_urls = ["https://quotes.toscrape.com"]
async def parse(self, response: Response):
for quote in response.css("div.quote"):
yield {
"text": quote.css("span.text::text").get(""),
"author": quote.css("small.author::text").get(""),
}
async def run_spider():
# Note: For production, consider using `MySpider().start()` which handles event loops.
# For direct asyncio integration as below, ensure no other event loop is running.
result = await QuotesSpider().start_async()
print(f"Scraped {len(result.items)} items with the spider.")
if result.items:
print(f"First item from spider: {result.items[0]}")
if __name__ == "__main__":
# Run the basic HTTP fetch synchronously
# The spider requires an async context if run outside `Spider().start()`
# For this example, we wrap it in asyncio.run
asyncio.run(run_spider())
Debug
Known issues
breakingVersion 0.4 introduced a new asynchronous Spider framework and significant API changes. Existing scraping logic written for previous versions, especially those not using the new Spider API, may require substantial refactoring. Users are advised to review the v0.4 release notes for specific breaking changes.fixConsult the official Scrapling documentation and v0.4 release notes for migration guidelines, especially for the new `Spider` framework and updated fetcher APIs.
affects: >=0.4.0
breakingIn version 0.3.13, Scrapling stopped using `Camoufox` entirely due to various reasons. If your existing scrapers relied on `Camoufox` integration, they will break or behave differently.fixReview the v0.3.13 release notes for instructions on how to continue using `Camoufox` if desired, or adapt your code to Scrapling's updated browser fetching mechanisms (e.g., `StealthyFetcher`, `DynamicFetcher`). [cite: GitHub releases]
affects: >=0.3.13
gotchaTo use browser-based fetchers (like `StealthyFetcher` or `DynamicFetcher`), `pip install scrapling` is not sufficient. You must also run `scrapling install` (or `playwright install` directly if Playwright is installed separately) to download the necessary browser binaries.fixAfter `pip install scrapling`, execute `scrapling install` in your terminal to ensure browser dependencies are set up correctly.
affects: All versions supporting browser fetchers
gotchaThe adaptive scraping feature, which allows selectors to auto-relocate elements after website changes, needs to be explicitly enabled using `auto_save=True` during initial scraping and `adaptive=True` for subsequent scraping runs.fixEnsure you set `auto_save=True` when first defining element patterns and `adaptive=True` when fetching pages where the structure might have changed to leverage this feature. Example: `page.css('.product', auto_save=True)` and later `page.css('.product', adaptive=True)`. affects: All versions supporting adaptive scraping
gotchaFor `TextHandler` and `Selector` classes, the method to retrieve all matched text or elements is `getall()` (e.g., `page.css('selector').getall()`), not `get_all()`.fixAlways use `getall()` when expecting a list of results from a selector. Version 0.4.3 unified this to match the `Selector` class.
affects: <0.4.3 (potential inconsistency), potentially later if used incorrectly
gotchaWhen running spiders, the `robots_txt_obey` option (introduced in v0.4.4) is disabled by default. If enabled, the spider will pre-fetch and respect `robots.txt` rules, including `Disallow`, `Crawl-delay`, and `Request-rate` directives, which can affect crawling speed and scope.fixSet `robots_txt_obey=True` in your spider's configuration if you need to comply with `robots.txt` rules. Be aware this might alter your crawl's behavior and speed. [cite: GitHub releases, 6]
affects: >=0.4.4
gotchaSupplying proxy credentials, CDP URLs, or user_data_dir paths can expose sensitive data or connect to untrusted remote browsers. Always ensure these sources are secure and trustworthy.fixExercise caution and validate the security of any external services or configurations (proxies, CDP endpoints) provided to Scrapling's fetchers or sessions.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'scrapling'
The 'scrapling' package is not installed in the current Python environment.
ImportError: cannot import name 'HTTPFetcher' from 'scrapling'
The 'HTTPFetcher' class is located within the 'scrapling.fetchers' submodule, not directly under the top-level 'scrapling' package.
fixfrom scrapling.fetchers import HTTPFetcher
selenium.common.exceptions.WebDriverException: Message: unknown error: Chrome failed to start: exited normally.
The underlying Chrome/Chromium browser instance required by 'StealthBrowserFetcher' or 'BrowserFetcher' failed to launch, often due to the browser not being installed, an incompatible version, or system environment issues.
fixEnsure a recent version of Google Chrome or Chromium is installed and accessible on your system. For containerized environments, ensure Chrome is included in the image.
TypeError: 'coroutine' object is not iterable
An asynchronous 'scrapling' method (e.g., 'get_async') was called but its returned coroutine object was used directly without 'await'ing it.
fiximport asyncio
from scrapling.fetchers import HTTPFetcher
async def main():
fetcher = HTTPFetcher()
response = await fetcher.get_async("http://example.com")
print(response.status)
if __name__ == "__main__":
asyncio.run(main()) Upgrade
Version history
0.4.9latest on PyPI · released Jun 7, 2026
Audit
Dependencies
PythonrequiredRequires Python 3.10 or higher.
PlaywrightrequiredUsed by browser-based fetchers (StealthyFetcher, DynamicFetcher) for headless automation. Binaries are installed via `scrapling install`.