<h1 align="center">
<a href="https://crawlee.dev">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/apify/crawlee-python/master/website/static/img/crawlee-dark.svg?sanitize=true">
<img alt="Crawlee" src="https://raw.githubusercontent.com/apify/crawlee-python/master/website/static/img/crawlee-light.svg?sanitize=true" width="500">
</picture>
</a>
<br>
<small>A web scraping and browser automation library</small>
</h1>
<p align=center>
<a href="https://badge.fury.io/py/crawlee" rel="nofollow">
<img src="https://badge.fury.io/py/crawlee.svg" alt="PyPI version" style="max-width: 100%;">
</a>
<a href="https://pypi.org/project/crawlee/" rel="nofollow">
<img src="https://img.shields.io/pypi/dm/crawlee" alt="PyPI - Downloads" style="max-width: 100%;">
</a>
<a href="https://pypi.org/project/crawlee/" rel="nofollow">
<img src="https://img.shields.io/pypi/pyversions/crawlee" alt="PyPI - Python Version" style="max-width: 100%;">
</a>
<a href="https://discord.gg/jyEM2PRvMU" rel="nofollow">
<img src="https://img.shields.io/discord/801163717915574323?label=discord" alt="Chat on discord" style="max-width: 100%;">
</a>
</p>
Crawlee covers your crawling and scraping end-to-end and **helps you build reliable scrapers. Fast.**
> 🚀 Crawlee for Python is open to early adopters!
Your crawlers will appear almost human-like and fly under the radar of modern bot protections even with the default configuration. Crawlee gives you the tools to crawl the web for links, scrape data and persistently store it in machine-readable formats, without having to worry about the technical details. And thanks to rich configuration options, you can tweak almost any aspect of Crawlee to suit your project's needs if the default settings don't cut it.
> 👉 **View full documentation, guides and examples on the [Crawlee project website](https://crawlee.dev/python/)** 👈
We also have a TypeScript implementation of the Crawlee, which you can explore and utilize for your projects. Visit our GitHub repository for more information [Crawlee for JS/TS on GitHub](https://github.com/apify/crawlee).
## Installation
We recommend visiting the [Introduction tutorial](https://crawlee.dev/python/docs/introduction) in Crawlee documentation for more information.
Crawlee is available as the [`crawlee`](https://pypi.org/project/crawlee/) PyPI package. The core functionality is included in the base package, with additional features available as optional extras to minimize package size and dependencies. To install Crawlee with all features, run the following command:
```sh
pip install 'crawlee[all]'
```
Then, install the [Playwright](https://playwright.dev/) dependencies:
```sh
playwright install
```
Verify that Crawlee is successfully installed:
```sh
python -c 'import crawlee; print(crawlee.__version__)'
```
For detailed installation instructions see the [Setting up](https://crawlee.dev/python/docs/introduction/setting-up) documentation page.
### With Crawlee CLI
The quickest way to get started with Crawlee is by using the Crawlee CLI and selecting one of the prepared templates. First, ensure you have [Pipx](https://pipx.pypa.io/) installed:
```sh
pipx --help
```
Then, run the CLI and choose from the available templates:
```sh
pipx run crawlee create my-crawler
```
If you already have `crawlee` installed, you can spin it up by running:
```sh
crawlee create my-crawler
```
## Examples
Here are some practical examples to help you get started with different types of crawlers in Crawlee. Each example demonstrates how to set up and run a crawler for specific use cases, whether you need to handle simple HTML pages or interact with JavaScript-heavy sites. A crawler run will create a `storage/` directory in your current working directory.
### BeautifulSoupCrawler
The [`BeautifulSoupCrawler`](https://crawlee.dev/python/api/class/BeautifulSoupCrawler) downloads web pages using an HTTP library and provides HTML-parsed content to the user. By default it uses [`HttpxHttpClient`](https://crawlee.dev/python/api/class/HttpxHttpClient) for HTTP communication and [BeautifulSoup](https://pypi.org/project/beautifulsoup4/) for parsing HTML. It is ideal for projects that require efficient extraction of data from HTML content. This crawler has very good performance since it does not use a browser. However, if you need to execute client-side JavaScript, to get your content, this is not going to be enough and you will need to use [`PlaywrightCrawler`](https://crawlee.dev/python/api/class/PlaywrightCrawler). Also if you want to use this crawler, make sure you install `crawlee` with `beautifulsoup` extra.
```python
import asyncio
from crawlee.beautifulsoup_crawler import BeautifulSoupCrawler, BeautifulSoupCrawlingContext
async def main() -> None:
crawler = BeautifulSoupCrawler(
# Limit the crawl to max requests. Remove or increase it for crawling all links.
max_requests_per_crawl=10,
)
# Define the default request handler, which will be called for every request.
@crawler.router.default_handler
async def request_handler(context: BeautifulSoupCrawlingContext) -> None:
context.log.info(f'Processing {context.request.url} ...')
# Extract data from the page.
data = {
'url': context.request.url,
'title': context.soup.title.string if context.soup.title else None,
}
# Push the extracted data to the default dataset.
await context.push_data(data)
# Enqueue all links found on the page.
await context.enqueue_links()
# Run the crawler with the initial list of URLs.
await crawler.run(['https://crawlee.dev'])
if __name__ == '__main__':
asyncio.run(main())
```
### PlaywrightCrawler
The [`PlaywrightCrawler`](https://crawlee.dev/python/api/class/PlaywrightCrawler) uses a headless browser to download web pages and provides an API for data extraction. It is built on [Playwright](https://playwright.dev/), an automation library designed for managing headless browsers. It excels at retrieving web pages that rely on client-side JavaScript for content generation, or tasks requiring interaction with JavaScript-driven content. For scenarios where JavaScript execution is unnecessary or higher performance is required, consider using the [`BeautifulSoupCrawler`](https://crawlee.dev/python/api/class/BeautifulSoupCrawler). Also if you want to use this crawler, make sure you install `crawlee` with `playwright` extra.
```python
import asyncio
from crawlee.playwright_crawler import PlaywrightCrawler, PlaywrightCrawlingContext
async def main() -> None:
crawler = PlaywrightCrawler(
# Limit the crawl to max requests. Remove or increase it for crawling all links.
max_requests_per_crawl=10,
)
# Define the default request handler, which will be called for every request.
@crawler.router.default_handler
async def request_handler(context: PlaywrightCrawlingContext) -> None:
context.log.info(f'Processing {context.request.url} ...')
# Extract data from the page.
data = {
'url': context.request.url,
'title': await context.page.title(),
}
# Push the extracted data to the default dataset.
await context.push_data(data)
# Enqueue all links found on the page.
await context.enqueue_links()
# Run the crawler with the initial list of requests.
await crawler.run(['https://crawlee.dev'])
if __name__ == '__main__':
asyncio.run(main())
```
### More examples
Explore our [Examples](https://crawlee.dev/python/docs/examples) page in the Crawlee documentation for a wide range of additional use cases and demonstrations.
## Features
Why Crawlee is the preferred choice for web scraping and crawling?
### Why use Crawlee instead of just a random HTTP library with an HTML parser?
- Unified interface for **HTTP & headless browser** crawling.
- Automatic **parallel crawling** based on available system resources.
- Written in Python with **type hints** - enhances DX (IDE autocompletion) and reduces bugs (static type checking).
- Automatic **retries** on errors or when you’re getting blocked.
- Integrated **proxy rotation** and session management.
- Configurable **request routing** - direct URLs to the appropriate handlers.
- Persistent **queue for URLs** to crawl.
- Pluggable **storage** of both tabular data and files.
- Robust **error handling**.
### Why to use Crawlee rather than Scrapy?
- **Asyncio-based** – Leveraging the standard [Asyncio](https://docs.python.org/3/library/asyncio.html) library, Crawlee delivers better performance and seamless compatibility with other modern asynchronous libraries.
- **Type hints** – Newer project built with modern Python, and complete type hint coverage for a better developer experience.
- **Simple integration** – Crawlee crawlers are regular Python scripts, requiring no additional launcher executor. This flexibility allows to integrate a crawler directly into other applications.
- **State persistence** – Supports state persistence during interruptions, saving time and costs by avoiding the need to restart scraping pipelines from scratch after an issue.
- **Organized data storages** – Allows saving of multiple types of results in a single scraping run. Offers several storing options (see [datasets](https://crawlee.dev/python/api/class/Dataset) & [key-value stores](https://crawlee.dev/python/api/class/KeyValueStore)).
## Running on the Apify platform
Crawlee is open-source and runs anywhere, but since it's developed by [Apify](https://apify.com), it's easy to set up on the Apify platform and run in the cloud. Visit the [Apify SDK website](https://docs.apify.com/sdk/python/) to learn more about deploying Crawlee to the Apify platform.
## Support
If you find any bug or issue with Crawlee, please [submit an issue on GitHub](https://github.com/apify/crawlee-python/issues). For questions, you can ask on [Stack Overflow](https://stackoverflow.com/questions/tagged/apify), in GitHub Discussions or you can join our [Discord server](https://discord.com/invite/jyEM2PRvMU).
## Contributing
Your code contributions are welcome, and you'll be praised for eternity! If you have any ideas for improvements, either submit an issue or create a pull request. For contribution guidelines and the code of conduct, see [CONTRIBUTING.md](https://github.com/apify/crawlee-python/blob/master/CONTRIBUTING.md).
## License
This project is licensed under the Apache License 2.0 - see the [LICENSE](https://github.com/apify/crawlee-python/blob/master/LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "crawlee",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "apify, automation, chrome, crawlee, crawler, headless, scraper, scraping",
"author": "Apify Technologies s.r.o.",
"author_email": "support@apify.com",
"download_url": "https://files.pythonhosted.org/packages/98/83/c048bf9b57e74fa54c85d321c69459dc10a527bc81fe5481ed2c51b450e7/crawlee-0.4.5.tar.gz",
"platform": null,
"description": "<h1 align=\"center\">\n <a href=\"https://crawlee.dev\">\n <picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/apify/crawlee-python/master/website/static/img/crawlee-dark.svg?sanitize=true\">\n <img alt=\"Crawlee\" src=\"https://raw.githubusercontent.com/apify/crawlee-python/master/website/static/img/crawlee-light.svg?sanitize=true\" width=\"500\">\n </picture>\n </a>\n <br>\n <small>A web scraping and browser automation library</small>\n</h1>\n\n<p align=center>\n <a href=\"https://badge.fury.io/py/crawlee\" rel=\"nofollow\">\n <img src=\"https://badge.fury.io/py/crawlee.svg\" alt=\"PyPI version\" style=\"max-width: 100%;\">\n </a>\n <a href=\"https://pypi.org/project/crawlee/\" rel=\"nofollow\">\n <img src=\"https://img.shields.io/pypi/dm/crawlee\" alt=\"PyPI - Downloads\" style=\"max-width: 100%;\">\n </a>\n <a href=\"https://pypi.org/project/crawlee/\" rel=\"nofollow\">\n <img src=\"https://img.shields.io/pypi/pyversions/crawlee\" alt=\"PyPI - Python Version\" style=\"max-width: 100%;\">\n </a>\n <a href=\"https://discord.gg/jyEM2PRvMU\" rel=\"nofollow\">\n <img src=\"https://img.shields.io/discord/801163717915574323?label=discord\" alt=\"Chat on discord\" style=\"max-width: 100%;\">\n </a>\n</p>\n\nCrawlee covers your crawling and scraping end-to-end and **helps you build reliable scrapers. Fast.**\n\n> \ud83d\ude80 Crawlee for Python is open to early adopters!\n\nYour crawlers will appear almost human-like and fly under the radar of modern bot protections even with the default configuration. Crawlee gives you the tools to crawl the web for links, scrape data and persistently store it in machine-readable formats, without having to worry about the technical details. And thanks to rich configuration options, you can tweak almost any aspect of Crawlee to suit your project's needs if the default settings don't cut it.\n\n> \ud83d\udc49 **View full documentation, guides and examples on the [Crawlee project website](https://crawlee.dev/python/)** \ud83d\udc48\n\nWe also have a TypeScript implementation of the Crawlee, which you can explore and utilize for your projects. Visit our GitHub repository for more information [Crawlee for JS/TS on GitHub](https://github.com/apify/crawlee).\n\n## Installation\n\nWe recommend visiting the [Introduction tutorial](https://crawlee.dev/python/docs/introduction) in Crawlee documentation for more information.\n\nCrawlee is available as the [`crawlee`](https://pypi.org/project/crawlee/) PyPI package. The core functionality is included in the base package, with additional features available as optional extras to minimize package size and dependencies. To install Crawlee with all features, run the following command:\n\n```sh\npip install 'crawlee[all]'\n```\n\nThen, install the [Playwright](https://playwright.dev/) dependencies:\n\n```sh\nplaywright install\n```\n\nVerify that Crawlee is successfully installed:\n\n```sh\npython -c 'import crawlee; print(crawlee.__version__)'\n```\n\nFor detailed installation instructions see the [Setting up](https://crawlee.dev/python/docs/introduction/setting-up) documentation page.\n\n### With Crawlee CLI\n\nThe quickest way to get started with Crawlee is by using the Crawlee CLI and selecting one of the prepared templates. First, ensure you have [Pipx](https://pipx.pypa.io/) installed:\n\n```sh\npipx --help\n```\n\nThen, run the CLI and choose from the available templates:\n\n```sh\npipx run crawlee create my-crawler\n```\n\nIf you already have `crawlee` installed, you can spin it up by running:\n\n```sh\ncrawlee create my-crawler\n```\n\n## Examples\n\nHere are some practical examples to help you get started with different types of crawlers in Crawlee. Each example demonstrates how to set up and run a crawler for specific use cases, whether you need to handle simple HTML pages or interact with JavaScript-heavy sites. A crawler run will create a `storage/` directory in your current working directory.\n\n### BeautifulSoupCrawler\n\nThe [`BeautifulSoupCrawler`](https://crawlee.dev/python/api/class/BeautifulSoupCrawler) downloads web pages using an HTTP library and provides HTML-parsed content to the user. By default it uses [`HttpxHttpClient`](https://crawlee.dev/python/api/class/HttpxHttpClient) for HTTP communication and [BeautifulSoup](https://pypi.org/project/beautifulsoup4/) for parsing HTML. It is ideal for projects that require efficient extraction of data from HTML content. This crawler has very good performance since it does not use a browser. However, if you need to execute client-side JavaScript, to get your content, this is not going to be enough and you will need to use [`PlaywrightCrawler`](https://crawlee.dev/python/api/class/PlaywrightCrawler). Also if you want to use this crawler, make sure you install `crawlee` with `beautifulsoup` extra.\n\n```python\nimport asyncio\n\nfrom crawlee.beautifulsoup_crawler import BeautifulSoupCrawler, BeautifulSoupCrawlingContext\n\n\nasync def main() -> None:\n crawler = BeautifulSoupCrawler(\n # Limit the crawl to max requests. Remove or increase it for crawling all links.\n max_requests_per_crawl=10,\n )\n\n # Define the default request handler, which will be called for every request.\n @crawler.router.default_handler\n async def request_handler(context: BeautifulSoupCrawlingContext) -> None:\n context.log.info(f'Processing {context.request.url} ...')\n\n # Extract data from the page.\n data = {\n 'url': context.request.url,\n 'title': context.soup.title.string if context.soup.title else None,\n }\n\n # Push the extracted data to the default dataset.\n await context.push_data(data)\n\n # Enqueue all links found on the page.\n await context.enqueue_links()\n\n # Run the crawler with the initial list of URLs.\n await crawler.run(['https://crawlee.dev'])\n\nif __name__ == '__main__':\n asyncio.run(main())\n```\n\n### PlaywrightCrawler\n\nThe [`PlaywrightCrawler`](https://crawlee.dev/python/api/class/PlaywrightCrawler) uses a headless browser to download web pages and provides an API for data extraction. It is built on [Playwright](https://playwright.dev/), an automation library designed for managing headless browsers. It excels at retrieving web pages that rely on client-side JavaScript for content generation, or tasks requiring interaction with JavaScript-driven content. For scenarios where JavaScript execution is unnecessary or higher performance is required, consider using the [`BeautifulSoupCrawler`](https://crawlee.dev/python/api/class/BeautifulSoupCrawler). Also if you want to use this crawler, make sure you install `crawlee` with `playwright` extra.\n\n```python\nimport asyncio\n\nfrom crawlee.playwright_crawler import PlaywrightCrawler, PlaywrightCrawlingContext\n\n\nasync def main() -> None:\n crawler = PlaywrightCrawler(\n # Limit the crawl to max requests. Remove or increase it for crawling all links.\n max_requests_per_crawl=10,\n )\n\n # Define the default request handler, which will be called for every request.\n @crawler.router.default_handler\n async def request_handler(context: PlaywrightCrawlingContext) -> None:\n context.log.info(f'Processing {context.request.url} ...')\n\n # Extract data from the page.\n data = {\n 'url': context.request.url,\n 'title': await context.page.title(),\n }\n\n # Push the extracted data to the default dataset.\n await context.push_data(data)\n\n # Enqueue all links found on the page.\n await context.enqueue_links()\n\n # Run the crawler with the initial list of requests.\n await crawler.run(['https://crawlee.dev'])\n\n\nif __name__ == '__main__':\n asyncio.run(main())\n```\n\n### More examples\n\nExplore our [Examples](https://crawlee.dev/python/docs/examples) page in the Crawlee documentation for a wide range of additional use cases and demonstrations.\n\n## Features\n\nWhy Crawlee is the preferred choice for web scraping and crawling?\n\n### Why use Crawlee instead of just a random HTTP library with an HTML parser?\n\n- Unified interface for **HTTP & headless browser** crawling.\n- Automatic **parallel crawling** based on available system resources.\n- Written in Python with **type hints** - enhances DX (IDE autocompletion) and reduces bugs (static type checking).\n- Automatic **retries** on errors or when you\u2019re getting blocked.\n- Integrated **proxy rotation** and session management.\n- Configurable **request routing** - direct URLs to the appropriate handlers.\n- Persistent **queue for URLs** to crawl.\n- Pluggable **storage** of both tabular data and files.\n- Robust **error handling**.\n\n### Why to use Crawlee rather than Scrapy?\n\n- **Asyncio-based** \u2013 Leveraging the standard [Asyncio](https://docs.python.org/3/library/asyncio.html) library, Crawlee delivers better performance and seamless compatibility with other modern asynchronous libraries.\n- **Type hints** \u2013 Newer project built with modern Python, and complete type hint coverage for a better developer experience.\n- **Simple integration** \u2013 Crawlee crawlers are regular Python scripts, requiring no additional launcher executor. This flexibility allows to integrate a crawler directly into other applications.\n- **State persistence** \u2013 Supports state persistence during interruptions, saving time and costs by avoiding the need to restart scraping pipelines from scratch after an issue.\n- **Organized data storages** \u2013 Allows saving of multiple types of results in a single scraping run. Offers several storing options (see [datasets](https://crawlee.dev/python/api/class/Dataset) & [key-value stores](https://crawlee.dev/python/api/class/KeyValueStore)).\n\n## Running on the Apify platform\n\nCrawlee is open-source and runs anywhere, but since it's developed by [Apify](https://apify.com), it's easy to set up on the Apify platform and run in the cloud. Visit the [Apify SDK website](https://docs.apify.com/sdk/python/) to learn more about deploying Crawlee to the Apify platform.\n\n## Support\n\nIf you find any bug or issue with Crawlee, please [submit an issue on GitHub](https://github.com/apify/crawlee-python/issues). For questions, you can ask on [Stack Overflow](https://stackoverflow.com/questions/tagged/apify), in GitHub Discussions or you can join our [Discord server](https://discord.com/invite/jyEM2PRvMU).\n\n## Contributing\n\nYour code contributions are welcome, and you'll be praised for eternity! If you have any ideas for improvements, either submit an issue or create a pull request. For contribution guidelines and the code of conduct, see [CONTRIBUTING.md](https://github.com/apify/crawlee-python/blob/master/CONTRIBUTING.md).\n\n## License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](https://github.com/apify/crawlee-python/blob/master/LICENSE) file for details.\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Crawlee for Python",
"version": "0.4.5",
"project_urls": {
"Apify Homepage": "https://apify.com",
"Changelog": "https://crawlee.dev/python/docs/changelog",
"Documentation": "https://crawlee.dev/python/docs/quick-start",
"Homepage": "https://crawlee.dev/python",
"Issue Tracker": "https://github.com/apify/crawlee-python/issues",
"Repository": "https://github.com/apify/crawlee-python"
},
"split_keywords": [
"apify",
" automation",
" chrome",
" crawlee",
" crawler",
" headless",
" scraper",
" scraping"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "78f02d89f06e3ef54d31ed4901e8860e9b5a176fc172580d016591a160f423a0",
"md5": "f43ed0a02fbffa9ae9806cbf4def2348",
"sha256": "cbb730bbd9fd08671344af9ff46af2be6e50a3e57011b82e58782c058f8c76c5"
},
"downloads": -1,
"filename": "crawlee-0.4.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f43ed0a02fbffa9ae9806cbf4def2348",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 196782,
"upload_time": "2024-12-06T10:04:12",
"upload_time_iso_8601": "2024-12-06T10:04:12.860611Z",
"url": "https://files.pythonhosted.org/packages/78/f0/2d89f06e3ef54d31ed4901e8860e9b5a176fc172580d016591a160f423a0/crawlee-0.4.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9883c048bf9b57e74fa54c85d321c69459dc10a527bc81fe5481ed2c51b450e7",
"md5": "8d0dbe2dfa0b36dea3fe61d2476aafd4",
"sha256": "c657eeb59d5471791e20801be23699cd1f03ad7883f126adedb6b3ed008c281d"
},
"downloads": -1,
"filename": "crawlee-0.4.5.tar.gz",
"has_sig": false,
"md5_digest": "8d0dbe2dfa0b36dea3fe61d2476aafd4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 143191,
"upload_time": "2024-12-06T10:04:14",
"upload_time_iso_8601": "2024-12-06T10:04:14.542262Z",
"url": "https://files.pythonhosted.org/packages/98/83/c048bf9b57e74fa54c85d321c69459dc10a527bc81fe5481ed2c51b450e7/crawlee-0.4.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-06 10:04:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "apify",
"github_project": "crawlee-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "crawlee"
}
JSON
