ichrome PyPI - Wheel PyPI - Python Version PyPI - Downloads PyPI - License

Chrome controller for Humans, based on Chrome Devtools Protocol(CDP) and python3.8+. Read Docs

🚀 [NEW] ichrome v6.0.1 is available! Now supporting ichrome.http - a RESTful API server to control Chrome via HTTP requests.

uvx --from ichrome ichrome.http
or
python -m ichrome.http
then view the interactive API docs at http://localhost:8080/docs

Want to add your own endpoints? Wrap tab operations as business logic into HTTP routes. See demo/custom_routes_guide.py for a quick guide.

If you encounter any problems, please let me know through issues; your feedback is valuable for enhancing ichrome.

Install

pip install ichrome -U

Uninstall & Clear the user data folder

    $ python3 -m ichrome --clean
    $ pip uninstall ichrome

Quick Start

import asyncio
from ichrome import AsyncChromeDaemon


async def test():
    async with AsyncChromeDaemon() as cd:
        # create a new tab
        async with cd.connect_tab(index=None) as tab:
            await tab.goto('https://github.com/ClericPy/ichrome', timeout=5)
            print(await tab.title)
        # Privacy Mode, proxyServer arg maybe not work on Chrome, for `Target.createBrowserContext` is the EXPERIMENTAL feature(but chromium is ok).
        # https://chromedevtools.github.io/devtools-protocol/tot/Target/#method-createBrowserContext
        async with cd.incognito_tab(proxyServer='http://127.0.0.1:8080') as tab:
            await tab.goto('https://httpbin.org/ip', timeout=5)
            print(await tab.html)


asyncio.run(test())

Why?

In desperate need of a stable toolkit to communicate with Chrome browser (or other Blink-based browsers such as Chromium)
- ichrome includes fast http & websocket connections (based on aiohttp) within an asyncio environment
Pyppeteer is awesome
- But I don't need so much, and the spelling of 'pyppeteer' is confusing
- Event-driven architecture (EDA) is not always ideal.
Selenium is slow
- Webdriver often comes with memory leaks
  - PhantomJS development is suspended
- No native coroutine (asyncio) support
Playwright arrived too late
- This may be a good choice for both sync and async usage
  - The original author of puppeteer joined the team.
- But its core code is based on Node.js, which is hard to monkey-patch.

Features

As we know, Javascript is the first-class citizen of the Browser world, so learn to use it frequently with ichrome.

A process daemon for Chrome instances
- auto-restart
- command-line usage
- async environment compatible
Connect to an existing Chrome
Operations on Tabs under stable websocket
- Commonly used functions
- Incognito Mode
ChromeEngine as the process pool
- support HTTP api router with aiohttp
  - python -m ichrome.http or uvx ichrome.http
  - python -m ichrome.http --help for usage
- ~~python -m ichrome.web (Removed since v6.0.0)~~
Flatten mode with sessionId
- Create only 1 WebSocket connection
- New in version 2.9.0
  - EXPERIMENTAL
  - Share the same Websocket connection and use sessionId to distinguish requests
- After v3.0.1
  - AsyncTab._DEFAULT_FLATTEN = True
The install script of chromium
debug mode for sync usage with ichrome.debugger >4.0.0 (EXPERIMENTAL)

Breaking Changes

v6.0.0
1. ichrome.web module is removed, use ichrome.http instead.
2. refactor the ChromeEngine method parameters.
  1. add wait condition before engine.do

Metadata

Release files for ichrome 6.0.1

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

Source distribution (sdist)

Source distribution for ichrome 6.0.1
File	Size	Uploaded
ichrome-6.0.1.tar.gz	152.2 kB	Apr 29, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for ichrome 6.0.1
File	Interpreter	ABI	Platform	Reset
ichrome-6.0.1-py3-none-any.whl 83.2 kB Apr 29, 2026	Python 3	none	any	Details

Total release size: 235.4 kB

Release files / ichrome-6.0.1.tar.gz

Download URL	ichrome-6.0.1.tar.gz
Size	152.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`a2bf78959a842ef411f335548edefd2f12e7fc181f485717b20fa49feef6e736`
BLAKE2b-256 checksum How to use checksums	`21bfdd5fc17d562752e52fcbcdf8e55fd7029b8f76ea409acac4ffe5b9a9fcd6`
Upload date	Apr 29, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`python-requests/2.33.1`

Release files / ichrome-6.0.1-py3-none-any.whl

Download URL	ichrome-6.0.1-py3-none-any.whl
Size	83.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`8153458722f3b6653538c18b3fc832f0209c303d3884f238f4b50c1df4c2038a`
BLAKE2b-256 checksum How to use checksums	`60f9a03084d58fe00e3fce81683ee3b331fd48dffbad1d847d700cc3958171f8`
Upload date	Apr 29, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`python-requests/2.33.1`