chromedp README

The project's README from github.com/chromedp/chromedp. As one markdown file: README.md.

About chromedp

Package chromedp is a faster, simpler way to drive browsers supporting the Chrome DevTools Protocol in Go without external dependencies.

Unit Tests Go Reference Releases

Installing

Install in the usual Go way:

$ go get -u github.com/chromedp/chromedp

Examples

Refer to the Go reference for the documentation and examples. Additionally, the examples repository contains more examples on complex actions, and other common high-level tasks such as taking full page screenshots.

Frequently Asked Questions

I can't see any Chrome browser window

By default, Chrome is run in headless mode. See DefaultExecAllocatorOptions, and an example to override the default options.

I'm seeing "context canceled" errors

When the connection to the browser is lost, chromedp cancels the context, and it may result in this error. This occurs, for example, if the browser is closed manually, or if the browser process has been killed or otherwise terminated.

Chrome exits as soon as my Go program finishes

On Linux, chromedp is configured to avoid leaking resources by force-killing any started Chrome child processes. If you need to launch a long-running Chrome instance, manually start Chrome and connect using RemoteAllocator.

Executing an action without Run results in "invalid context"

By default, a chromedp context does not have an executor, however one can be specified manually if necessary; see issue #326 for an example.

I can't use an Action with Run because it returns many values

Wrap it with an ActionFunc:

ctx, cancel := chromedp.NewContext(context.Background())
defer cancel()
chromedp.Run(ctx, chromedp.ActionFunc(func(ctx context.Context) error {
	_, err := domain.SomeAction().Do(ctx)
	return err
}))

I want to use chromedp on a headless environment

The simplest way is to run the Go program that uses chromedp inside the chromedp/headless-shell image. That image contains headless-shell, a smaller headless build of Chrome, which chromedp is able to find out of the box.

Resources

chromedp (chromedp/chromedp)

Searching Database…

13.3K ·GitHub
Chromedp
What is this?chromedp is a Go library that drives any browser supporting the Chrome DevTools Protocol — a faster, simpler way to automate Chrome from Go code, with no external dependencies.
Is it a library I import into Go code, or a tool I run from the terminal?A Go package, not a standalone tool: your Go code imports chromedp and controls a real Chrome browser through it. There is no CLI.
How do I add it to a Go project?Install it like any Go module ('go get github.com/chromedp/chromedp'), then start from the Go reference docs; the separate chromedp/examples repository has more advanced samples.
Do I need to have Chrome installed, or does chromedp bring its own browser?You need a local Chrome for it to control — chromedp launches the browser itself, headless by default. The module itself adds no external Go dependencies.
Why can't I see a browser window when my program runs?Chrome starts headless unless you change that: override the defaults through DefaultExecAllocatorOptions to get a visible browser window.
Does it work only on Linux, or on other systems too?The README explicitly covers Linux behavior and headless setups; as a pure-Go library with no external dependencies, it runs wherever Go and a Chrome-family browser are available.
I want to run this on a displayless server — what's the simplest way?Run your program inside the chromedp/headless-shell Docker image — it ships a smaller headless build of Chrome that chromedp finds out of the box.
Why does Chrome close as soon as my Go program finishes?That is intentional on Linux: chromedp force-kills the Chrome child processes it started so they never leak resources. For a long-lived browser, start Chrome yourself and connect with RemoteAllocator.
What does a 'context canceled' error mean?The connection to the browser was lost — the window was closed or the Chrome process was killed — so chromedp cancels the context your actions were running in.
Where can I find example code beyond the docs?The Go reference holds the main documentation and examples, and the chromedp/examples repository shows complex actions plus common high-level tasks like taking full-page screenshots.
What are similar projects?moli, pinchtab, browser, chrome-devtools-mcp, web-access, stealth-browser-mcp, chromeless, playwright
Which topics is it in?chrome-devtools, cdp, headless, unit-testing, chrome, devtools, web-scraping, browser-automation, golang, testing, browser, go
Creator
chromedp
Size
3.3 MB
Stars
13.3K
Updated
CommitOct 11Releasev0.21.0Oct 11
Age
9y
Commits · 90 Days