About chromedp examples
This repository holds 44 example programs for chromedp, a Go package that
drives Chrome through the Chrome DevTools Protocol. The package documentation
has small examples that are self-contained. These programs are larger. Only the
program fast needs the internet. The program extension needs the files of
uBlock Origin Lite on disk. The program remote needs a Chrome with a debugging
port, unless you use its flag -start.
The programs use the typed API of chromedp v0.21.0 and cdproto v0.157.8.
The file docs/API.md in the chromedp repository shows the old code and the
new code side by side. The file docs/MIGRATION.md in the same folder lists
every name that changed. See
the decision for the port.
Build and run
The module needs Go 1.27. The packages chromedp, cdproto and termcast need
only Go 1.25 or later. The module requires chromedp v0.21.0, cdproto v0.157.8
and termcast v0.2.2, and Go downloads them when you build a program. The
programs use the package chromedp/remote, which is part of chromedp, for the
flag -visible, which keeps the browser open, and for the remote program.
They use termcast for the flag -visible-on-terminal.
The tags of this repository follow the tags of chromedp. The tag v0.21.0 holds
programs that use chromedp v0.21, and a tag such as v0.21.1 is a later change in
this repository.
chromedp starts the browser. It finds Chrome or Chromium on the PATH. If
Chrome has another name, link it to the name google-chrome in a folder on the
PATH. Run a program from the root of this repository:
# run the program <prog>, for example go run ./click
$ go run ./<prog>
# build the program <prog>
$ go build -o /tmp/<prog> ./<prog> && /tmp/<prog>
Every program accepts the flag -v. It prints the protocol messages between
the program and the browser. Without -v, a program prints only its own output.
For example, go run ./cookie -v shows the protocol messages. Run
go run ./<prog> -h to see all flags of a program. Put the flags of a program
after its folder, as in go run ./multi -out out <url>.
Every program except remote accepts the flag -visible. It shows the browser
window instead of a headless browser, and it leaves the browser open when the
program ends. The program prints the websocket address and the profile directory
of the browser to the standard error. The browser stays running until you close
its window, and the profile directory stays on disk until you delete it. To show
the window with no flag, set the variable CHROMEDP_VISIBLEWINDOW=1. Any value
other than an empty string, 0 and false turns it on. On Linux, a visible
window needs DISPLAY or WAYLAND_DISPLAY. The remote program has
no -visible flag, because it attaches to a browser that you started yourself.
The flag -visible has no effect on the remote browser of forecast -remote.
The tabs program works a little differently with -visible. It keeps every tab
open and waits until you close the browser, and it does not leave the browser
running. Its flag -tabs-in-one-window opens the tabs in one window, as real
tabs, and switches between them with the protocol command Target.activateTarget.
Without that flag, each tab opens in a window of its own. Try both with
-visible to see the difference.
Some programs need arguments:
forecast needs the flag -q, for example go run ./forecast -q Jakarta.geoip takes IP addresses, for example go run ./geoip 8.8.8.8.multi takes URLs. See multi/README.md.remote needs a running browser, or the flag -start. See
remote/README.md.extension needs the flag -ext with the files of uBlock Origin Lite.upload uploads its own source file, so you can run it from any folder.
The programs download_file, download_image, emulate, har, pdf,
pdfstream and screenshot write files into the current directory. The
programs fast and forecast write a file only when you give the flag -out,
and multi does so only with its flag -out. The programs pdfoptions and
screencast write their files into a new temporary directory, or into the
directory of their flag -out.
The programs
| Example | Description |
|---|
| click | use a selector to click on an element |
| console | read the console of a page and its uncaught exceptions with chromedp |
| cookie | set an HTTP cookie on requests |
| dialogs | handle the JavaScript dialogs of a page |
| distrust | check that a browser rejects the certificates of a compromised certificate authority |
| download_file | do headless file downloads |
| download_image | do headless image downloads |
| dragdrop | drag and drop with the actions DragAndDrop and DragAndDropXY |
| emulate | emulate a specific device such as an iPhone |
| eval | evaluate JavaScript and retrieve the result |
| eventsiter | listen to the events of a page with iterators |
| exposefunc |
The programs fast, forecast, geoip and remote draw an image in the
terminal. Run them in a terminal that can show images. Most other programs have
the flag -visible-on-terminal, which the section Draw the page in the
terminal describes.
Draw the page in the terminal
Most programs take the flag -visible-on-terminal. It draws the page of the
program in the terminal while the program runs, with terminal graphics (Kitty,
iTerm2 or Sixel). The flag also works with a headless browser over ssh. The
package termcast does this work. It uses the screencast of the
Chrome DevTools Protocol and 4 frames each second by default. Use the flag
-terminal-fps to change the rate.
go run github.com/chromedp/examples/click@latest -visible-on-terminal
The stream clears the terminal at each redraw. It holds the log lines and the
results of the program, and prints them after the final frame. The flag does not
work with -v, and it stops with an error when the terminal has no graphics.
The programs tabs, popups, workers, multi, session, screencast,
pdfstream, har and rawcall do not have the flag. The program termcast
has the flag -fps and not the two flags. It shows how to use the package in
your own code. It plays an animated SVG and streams it to the terminal.
Verification
The table says which programs run with the current API, and what each program
needs. "Offline" means that the program needs no internet and no service. A
program that needs a live site reads it from the internet. A program that needs
a terminal draws an image with rasterm. Every program runs in a headless
Chrome unless you set the flag -visible, so no program in the table needs a
display.
The column "Checked" says how the result was found. "Run on 2026-10-04" means that
the offline programs ran with go run, with Chrome 154 on Linux, and finished
with exit code 0. "Earlier test" means a run of the same code with Chrome 154 on
Linux before that date. These programs were not run again on 2026-10-04,
because they need a live site that can change. No program was run with the flag
-visible.
| Example | Needs | Result with the current API | Checked |
|---|
| click | offline | works | run on 2026-10-04 |
| console | offline | works | run on 2026-10-04 |
| cookie | offline | works | run on 2026-10-04 |
| dialogs | offline | works | run on 2026-10-04 |
| distrust | internet, Podman | works, the browser connected to 7 of 14 hosts | run on 2026-10-26 |
| download_file | offline | works | run on 2026-10-04 |
| download_image | offline | works | run on 2026-10-04 |
| dragdrop | offline | works | run on 2026-10-04 |
| emulate | offline | works | run on 2026-10-04 |
| eval | offline | works | run on 2026-10-04 |
| eventsiter | offline | works | run on 2026-10-04 |
| exposefunc | offline | works | run on 2026-10-04 |
| extension | offline, the uBlock Origin Lite files on disk | works | run on 2026-10-04 |
| fast | internet (fast.com), terminal | needs a terminal that shows images | earlier test |
| forecast | terminal | works in a terminal, stops without one | run on 2026-10-04 |
| frames | offline | works | run on 2026-10-04 |
| geoip | terminal | works in a terminal, stops without one | run on 2026-10-04 |
| har | offline | works | run on 2026-10-04 |
| headers | offline | works | run on 2026-10-04 |
| intercept | offline | works | run on 2026-10-04 |
| keys | offline | works | run on 2026-10-04 |
|
Notes:
- The programs
forecast and geoip draw an image with rasterm. Without a
terminal that shows images, they stop with the error term graphics not available. fast does the same, and it reads the live site fast.com.
- The programs
geoip and forecast embed their data files, GeoLite2-City.mmdb
and hl.json, so they run from any folder.
remote needs a Chrome that runs with a debugging port, for example
chrome --headless --remote-debugging-port=9222. Use the flag -start to
let remote start that Chrome.- Every other program except
distrust reads local content. These programs read the local test
site in internal/testsite, and they take the flag -url to read another
site: click, download_file, download_image, emulate, eval,
extension, forecast, geoip, latlon, logic, pdf, screenshot,
submit, termcast and text. The program remote takes the flag -nav.
The other programs serve their own page from a local server.
extension needs the files of uBlock Origin Lite on disk. Use the flag
-ext.distrust starts the image headless-shell in a container with Podman,
and reads the test page emudhra.we-have-a-problem.com and its test hosts.
Use the flag -podman to name another command, such as docker. On
2026-10-26 the image latest was Chrome 157.0.8103.15. The browser connected
to the 7 hosts that chain to the root of eMudhra, so it still trusted the
compromised intermediate certificates, and the program ended with the
status 1. Chrome blocks these certificates with an update of its CRLSet,
and the image does not receive that update.
Live sites can change
fast reads the live site fast.com, and distrust reads the test page
emudhra.we-have-a-problem.com. Their results can be different on another day.
Questions, bugs and changes
Ask questions in the GitHub Discussions of chromedp. Report a bug as an
issue of chromedp. Do not open an issue for a question. Pull requests
are welcome, and CONTRIBUTING.md says how to prepare one. A new program must
keep to the rules in AGENTS.md.
