Browse by type
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]
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 core 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 a
second module, github.com/chromedp/chromedp/remote. Install 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:
go get -u github.com/chromedp/chromedp/remote
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.
The [examples][chromedp-examples] repository has 43 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
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:
Network, sessions and files:
Events and the protocol:
Screens and devices:
termcast.Several tabs and browsers:
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 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.
[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. The stream clears the terminal at
each redraw. It holds the log lines while it
runs, and prints them after the final frame. The type termcast.Flags adds the
flags -visible-on-terminal and -terminal-fps to a program, as the programs
in the [examples][chromedp-examples] repository have them.
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 module 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.
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.
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
websocket and a debugging port instead, add the remote.WebSocket option of the
module github.com/chromedp/chromedp/remote to the exec allocator. A
remote-debugging-port or remote-debugging-address flag also selects the
websocket, and so does KeepOpen, and they all need remote.WebSocket. A
program for Windows needs no remote module for the default pipe.
Chrome exits as soon as my Go program finishes
On Linux, chromedp kills the Chrome child processes that it started, so that no
resources leak. To leave Chrome open, add remote.WithKeepOpen. See
Visible browser. You can also start Chrome yourself and
connect with remote.NewAllocator.
Calling an action or a command results in "invalid context"
chromedp.Do, chromedp.Run and chromedp.Call need a context that came from
chromedp.NewContext, because the context holds the browser and the tab. Any
other context gives ErrInvalidContext.
How do I send a protocol command that has no action?
Call it with chromedp.Call, which runs the command on the tab of the context:
```go ctx, cancel := chromedp.NewCon
browse all types & interfaces →
$ claude mcp add chromedp \
-- python -m otcore.mcp_server <graph>