MCPcopy Create free account
hub / github.com/chromedp/chromedp

github.com/chromedp/chromedp

Chat with this repo
repository ↗ · DeepWiki ↗ · release v0.24.0 ↗ · + Follow · compare 5 versions
1,147 symbols 5,942 edges 109 files 722 documented · 63% ● updated 45d agov0.19.1 · 2026-10-04★ 13,297

Browse by type

⨍ Functions 1,064◇ Types & classes 83
What it actually does AI analysis from the code graph — generated when you open this
loading…
README

About chromedp

chromedp logo

Package chromedp drives browsers that speak the [Chrome DevTools Protocol][devtools-protocol] from Go. It needs no external driver.

[![Unit Tests][chromedp-ci-status]][chromedp-ci] [![Go Reference][goref-chromedp-status]][goref-chromedp] [![Releases][release-status]][releases] [![Discord Discussion][discord-status]][discord]

Installing

Install the package with go get. The module needs Go 1.25 or newer. The JSON types come from github.com/chromedp/cdproto/cdp/jsonv2. They are aliases of the types of the standard library package encoding/json/v2 on Go 1.27 and later, or on Go 1.25 and 1.26 with GOEXPERIMENT=jsonv2. Otherwise they are aliases of the types of github.com/go-json-experiment/json. Version v0.20.0 uses the typed cdproto v0.157.8 and has the generic and iterator API. The earlier versions of cdproto, v0.157.0, v0.157.1 and v0.157.2, have the old API.

go get -u github.com/chromedp/chromedp

The module uses only the Go standard library and cdproto. It starts a browser and talks to it through a pipe. Code that needs a websocket is in the package github.com/chromedp/chromedp/remote, which has its own WebSocket client. It is part of the same module, so go get installs it with the rest. Import it only when you connect to a browser that runs already, when you want the exec allocator to use a websocket, or when you keep the browser open after the program ends.

Usage

An action is a func that runs against a browser tab and returns a value. chromedp.Do runs actions that return nothing, and chromedp.Run runs one action and returns its value:

ctx, cancel := chromedp.NewContext(context.Background())
defer cancel()

if err := chromedp.Do(ctx, chromedp.Navigate(`https://pkg.go.dev/`)); err != nil {
    log.Fatal(err)
}
title, err := chromedp.Run(ctx, chromedp.Title())
if err != nil {
    log.Fatal(err)
}
fmt.Println(title)

A page event is an iterator. chromedp.Events subscribes when it returns, so a program can subscribe, trigger the event, and then read it:

loaded := chromedp.Events(ctx, page.LoadEventFired)
if err := chromedp.Do(ctx, chromedp.Navigate(`https://pkg.go.dev/`)); err != nil {
    log.Fatal(err)
}
for ev, err := range loaded {
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(ev.Timestamp)
    break
}

docs/API.md describes the API. It has 27 examples that show the old code and the new code side by side. docs/MIGRATION.md lists every renamed and removed name.

See the [Go reference][goref-chromedp] for the documentation and examples.

More examples

The [examples][chromedp-examples] repository has 46 programs for larger tasks. Each program is one main.go file. Run one with go run, for example go run github.com/chromedp/examples/tabs@latest. Every program takes the flag -v to print the protocol messages. Every program except remote takes the flag -visible to show the browser window. Most programs take the flag -visible-on-terminal to draw the page in the terminal while they run, with termcast. Every program except fast and distrust reads local content and needs no internet. Some programs take the flag -url to read another site. The program termcast takes the flag -fps instead of -visible-on-terminal.

Read pages and fill forms:

  • click clicks an element that a selector finds.
  • text reads the text of an element.
  • eval runs JavaScript in the page and decodes the result.
  • structeval decodes JavaScript results into Go structs, slices and maps, and shows the errors.
  • logic mixes actions and Go code to read a list.
  • subtree walks a subtree of the DOM.
  • selectors shows the typed selectors side by side.
  • frames reaches elements inside an iframe and a shadow root.
  • submit fills out and submits a form.
  • keys sends key events to an element.
  • upload uploads a file on a form.
  • visible waits until an element is visible.
  • dragdrop drags and drops with the mouse and with HTML5 drag and drop.

Network, sessions and files:

  • cookie sets cookies on requests.
  • headers adds extra HTTP headers.
  • proxy signs in to a proxy server that needs a password.
  • intercept blocks, mocks and changes requests with the Fetch domain.
  • session saves a login session and restores it in another browser.
  • har writes a HAR file from the network events of a page, with Listen.
  • download_file downloads a file with a headless browser.
  • download_image downloads an image from the network response.

Events and the protocol:

  • eventsiter reads the events of a page with iterators, and waits for the network to be idle.
  • timeline puts the events of every type in one timeline, in the order in which Chrome sent them, with Listen.
  • contexts attaches to a tab that runs already and lists its JavaScript contexts, with WithListener and Detached.
  • console reads the console and the uncaught exceptions of a page.
  • dialogs answers alert, confirm, prompt and beforeunload dialogs.
  • popups works with popups and several targets, and with browser contexts.
  • exposefunc calls Go functions from the page.
  • extension loads a browser extension, uBlock Origin Lite, from a folder on disk and shows that it blocks the ads of a page.
  • latlon drives a map and reads the latitude and the longitude from the URL of the page.
  • rawcall sends protocol commands that have no action, such as timezone, locale, geolocation and throttling.

Screens and devices:

  • screenshot takes a screenshot of an element and of the whole page.
  • pdf prints a page to a PDF file.
  • pdfoptions prints a page to PDF files with different options.
  • pdfstream reads a printed PDF as a stream.
  • emulate emulates a device, such as an iPhone.
  • screencast saves the frames of a page as JPEG files.
  • termcast plays an animated SVG and streams the screen of the browser to the terminal with termcast.

Several tabs and browsers:

  • tabs uses several tabs of one browser, with or without a window for each tab, and switches between them.
  • workers runs many jobs at the same time in one browser with a pool of goroutines.
  • multi uses the headless-shell image in a container.
  • distrust starts the headless-shell image in a container with Podman and checks that the browser rejects the certificates of a compromised certificate authority.
  • remote connects to a browser that is already running, with the package remote.

The program fast reads a live site, fast.com, and draws an image in the terminal. It can fail when the site changes. The program distrust reads the test page emudhra.we-have-a-problem.com. The programs forecast and geoip also draw an image in the terminal. Run these programs in a terminal that can show images. The tags of the examples repository follow the tags of chromedp.

Show the browser in the terminal

[termcast][termcast] streams the screen of a chromedp page to a terminal that can show images (Kitty, iTerm2 or Sixel). It uses the screencast of the Chrome DevTools Protocol, so it works with a headless browser, also over ssh. Start the browser first, and then start the stream with the context.

ctx, cancel := chromedp.NewContext(context.Background())
defer cancel()
chromedp.Do(ctx, chromedp.Navigate("https://example.com")) // starts the browser
s, err := termcast.Start(ctx)                               // draws 4 frames each second
if err != nil {
    log.Fatal(err) // termcast.ErrNoGraphics when the terminal has no graphics
}
defer s.Stop()

To draw one element and not the whole page, add termcast.WithElement(chromedp.CSS("#chart")) to the call of termcast.Start. The module termcast needs Go 1.25 or newer. Start detects the graphics of the terminal. In kitty and Ghostty, the stream changes the picture with no flicker, and in other terminals it clears the terminal at each redraw. It holds the log lines while it runs, and prints them after the final frame.

termcast has no flags. The program owns its flags and calls termcast.Start only when a flag asks for the stream. A nil stream is a stream that is off, so defer s.Stop() and log.SetOutput(s.LogWriter()) work in either case. The programs in the [examples][chromedp-examples] repository define the flags -visible-on-terminal and -terminal-fps with a small helper of their own.

Visible browser

By default, chromedp runs Chrome in headless mode, so no window opens. To see the browser, add WithVisibleWindow. Set the variable CHROMEDP_VISIBLEWINDOW=1 to get the same result with no change in the code. On Linux, a visible window needs DISPLAY or WAYLAND_DISPLAY. Without them, the first Run returns chromedp.ErrNoDisplay.

ctx, cancel := chromedp.NewContext(context.Background(), chromedp.WithVisibleWindow())
defer cancel()
chromedp.Do(ctx, chromedp.Navigate("https://example.com"))
chromedp.WaitClosed(ctx) // block until the user closes the window

To leave the browser open after the program ends, add remote.WithKeepOpen from the package github.com/chromedp/chromedp/remote. The program can print the address, and another program can attach to it with remote.NewAllocator. The profile directory stays on disk, and you must delete it yourself.

ctx, _ := chromedp.NewContext(context.Background(), chromedp.WithVisibleWindow(), remote.WithKeepOpen())
chromedp.Do(ctx, chromedp.Navigate("https://example.com"))
wsURL, profile := chromedp.KeptOpen(ctx)
fmt.Println("attach to", wsURL, "profile", profile)
// The program ends here. The browser stays open.

Remote browser

To connect to a browser that runs already, such as a container or a hosted service, use remote.NewAllocator with the websocket address of the browser:

allocCtx, cancel := remote.NewAllocator(context.Background(), "ws://127.0.0.1:9222/")
defer cancel()
ctx, cancel := chromedp.NewContext(allocCtx)
defer cancel()
title, err := chromedp.Run(ctx, chromedp.Title())

A hosted service can need a header on the websocket request. Give the full address of the browser and the options remote.NoModifyURL and remote.WithDialHTTPHeader.

Frequently Asked Questions

I cannot see any Chrome browser window

By default, chromedp runs Chrome in headless mode. See Visible browser. See also DefaultExecAllocatorOptions, and see [an example][goref-chromedp-exec-allocator] that overrides the default options.

I see "context canceled" errors

When the connection to the browser is lost, chromedp cancels the context. This can cause the error. It happens, for example, when someone closes the browser by hand, or when something kills the browser process. When the browser process dies on its own, the error also holds the exit error of the process. Use errors.As with an *exec.ExitError to read the signal or the exit status.

How does chromedp talk to the browser it starts?

By default, through a pipe. chromedp starts Chrome with --remote-debugging-pipe and two pipes, so Chrome opens no debugging port. On Windows the pipes are handles that the switch --remote-debugging-io-pipes names. To use a w

Extension points exported contracts — how you extend this code

browse all types & interfaces →

Core symbols most depended-on inside this repo

browse all functions →

Shape

Function 914
Method 150
Struct 57
TypeAlias 16
Interface 7
FuncType 3

Languages

Go92%
TypeScript8%

Modules by API surface

query_test.go84 symbols
query.go80 symbols
testdata/twgl-full.min.js75 symbols
allocate.go50 symbols
chromedp_test.go36 symbols
chromedp.go36 symbols
util.go31 symbols
remote/internal/websocket/handshake_test.go30 symbols
example_test.go30 symbols
remote/internal/websocket/conn_test.go27 symbols
browser.go25 symbols
allocate_test.go24 symbols

Dependencies from manifests, versioned

github.com/chromedp/cdprotov0.160.1 · 1×
github.com/go-json-experiment/jsonv0.0.0-2026021321034 · 1×
github.com/ledongthuc/pdfv0.0.0-2022030213484 · 1×
github.com/orisano/pixelmatchv0.0.0-2022072200265 · 1×

For agents

$ claude mcp add chromedp \
  -- python -m otcore.mcp_server <graph>

⬇ download graph artifact

Ask about this repo answers extend the page