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 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.
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 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:
Network, sessions and files:
Listen.Events and the protocol:
Listen.WithListener and Detached.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 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.
[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.
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.
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
w
browse all types & interfaces →
$ claude mcp add chromedp \
-- python -m otcore.mcp_server <graph>