Guide · Open source

How to use chromedp: install, run actions and take screenshots in Go

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

chromedp is a Go package that lets a program control a web browser: opening pages, clicking, reading text, filling forms, taking screenshots and printing PDFs. It works with browsers that support the Chrome DevTools Protocol and, according to its README, needs no separate driver program. This guide is for people who write Go and want to automate or test web pages; after reading it you will know how to install the package, run actions against a browser tab and find the examples to adapt.

chromedpchromedp/chromedp · ★ 13.3k · MIT Install options & downloads

Quick start

1Check prerequisites. Confirm you have Go 1.25 or newer and a Chrome or Chromium-based browser installed.
2Install the package. Run go get -u github.com/chromedp/chromedp in your module.
3Create a context. Call chromedp.NewContext with context.Background() and defer the cancel function.
4Run an action. Use chromedp.Do for actions with no return value and chromedp.Run for actions that return a value, such as chromedp.Title().
5Try an example. Run a program from the examples repository with go run, adding -visible to see the browser window.

What chromedp needs before you install it

You need Go 1.25 or newer, because the module requires it. You also need a Chrome or Chromium-based browser installed. The README does not state the exact browser requirement, but the package is built to drive browsers that speak the Chrome DevTools Protocol.

Go 1.25 or newer
A Chrome or Chromium-based browser installed

Install chromedp with go get

Install the package with go get. The README says the module uses only the Go standard library and cdproto, and that no external driver is needed. The package is MIT licensed.

go get -u github.com/chromedp/chromedp

Run your first actions in a browser tab

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. The example below opens a page and reads its title. Always call cancel when you are done, so the browser is shut down.

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)

Wait for page events

A page event is an iterator. chromedp.Events subscribes when it returns, so a program can subscribe first, trigger the event, and then read it. This pattern avoids missing an event that fires during navigation.

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
}

Find ready-made examples to copy from

The examples repository has 43 programs, each a single main.go file that you can run with go run. The README lists examples for reading pages, filling forms, handling network requests, taking screenshots and printing PDFs. Each program takes a -v flag to print protocol messages, and most take -visible to show the browser window.

For the full API, read docs/API.md, which has 27 examples showing old and new code side by side. docs/MIGRATION.md lists every renamed and removed name.

click: clicks an element that a selector finds
text: reads the text of an element
submit: fills out and submits a form
session: saves a login session and restores it in another browser
screenshot: takes a screenshot of an element and of the whole page
pdf: prints a page to a PDF file

go run github.com/chromedp/examples/tabs@latest

Keep the browser open or connect to a running one

Code that needs a websocket lives in the package github.com/chromedp/chromedp/remote. Import it only when you connect to a browser that is already running, when the exec allocator should use a websocket, or when you keep the browser open after the program ends. The remote example shows the connection.

What people use it for

Testing a Go web application's pages in code with unit-test style tooling
Scraping text from pages with a selector and printing the result
Taking screenshots of a page or a single element
Printing a web page to a PDF file
Saving a logged-in browser session and restoring it later

Frequently asked questions

Is chromedp free to use?

Yes. chromedp is licensed under the MIT licence, according to the project's listing. You can use, modify and distribute it under those terms.

Do I need to install a separate driver for chromedp?

No. According to the README, chromedp needs no external driver. It starts a browser and talks to it through a pipe.

What version of Go do I need for chromedp?

The README says the module needs Go 1.25 or newer. Install that version before running go get.

Can I use chromedp without writing Go?

Not directly. chromedp is a Go package and the README shows only Go code. If you do not write Go, a point-and-click tool or a tool in another language may suit you better.

How does chromedp compare with Rod, Playwright, Selenium and Puppeteer?

The source does not include a comparison. It lists Rod, Playwright, Selenium and Puppeteer as comparable projects. Choose chromedp if your code is in Go; choose another project if you need one automation standard across several languages.

Why does my program fail to start the browser?

The source does not give troubleshooting steps. Check that a Chrome or Chromium-based browser is installed and that you use Go 1.25 or newer, then compare your code with the examples repository.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

chromedp suits Go developers who want to test, scrape, screenshot or print web pages from code, and it needs no separate driver. It is not a good choice for people who do not write Go or who need one automation library across many languages, where Playwright, Selenium or Puppeteer may fit better.

Install options & downloads