goquery README

The project's README from github.com/PuerkitoBio/goquery. As one markdown file: README.md.

goquery - a little like that j-thing, only in Go

Build Status Go Reference Sourcegraph Badge

goquery brings a syntax and a set of features similar to jQuery to the Go language. It is based on Go's net/html package and the CSS Selector library cascadia. Since the net/html parser returns nodes, and not a full-featured DOM tree, jQuery's stateful manipulation functions (like height(), css(), detach()) have been left off.

Also, because the net/html parser requires UTF-8 encoding, so does goquery: it is the caller's responsibility to ensure that the source document provides UTF-8 encoded HTML. See the wiki for various options to do this.

Syntax-wise, it is as close as possible to jQuery, with the same function names when possible, and that warm and fuzzy chainable interface. jQuery being the ultra-popular library that it is, I felt that writing a similar HTML-manipulating library was better to follow its API than to start anew (in the same spirit as Go's fmt package), even though some of its methods are less than intuitive (looking at you, index()...).

Table of Contents

Installation

Required Go version:

Ongoing goquery development is tested on the latest 2 versions of Go.

$ go get github.com/PuerkitoBio/goquery

(optional) To run unit tests:

$ cd $GOPATH/src/github.com/PuerkitoBio/goquery
$ go test

(optional) To run benchmarks (warning: it runs for a few minutes):

$ cd $GOPATH/src/github.com/PuerkitoBio/goquery
$ go test -bench=".*"

Changelog

Note that goquery's API is now stable, and will not break.

API

goquery exposes two structs, Document and Selection, and the Matcher interface. Unlike jQuery, which is loaded as part of a DOM document, and thus acts on its containing document, goquery doesn't know which HTML document to act upon. So it needs to be told, and that's what the Document type is for. It holds the root document node as the initial Selection value to manipulate.

jQuery often has many variants for the same function (no argument, a selector string argument, a jQuery object argument, a DOM element argument, ...). Instead of exposing the same features in goquery as a single method with variadic empty interface arguments, statically-typed signatures are used following this naming convention:

Utility functions that are not in jQuery but are useful in Go are implemented as functions (that take a *Selection as parameter), to avoid a potential naming clash on the *Selection's methods (reserved for jQuery-equivalent behaviour).

The complete package reference documentation can be found here.

Please note that Cascadia's selectors do not necessarily match all supported selectors of jQuery (Sizzle). See the cascadia project for details. Also, the selectors work more like the DOM's querySelectorAll, than jQuery's matchers - they have no concept of contextual matching (for some concrete examples of what that means, see this ticket). In practice, it doesn't matter very often but it's something worth mentioning. Invalid selector strings compile to a Matcher that fails to match any node. Behaviour of the various functions that take a selector string as argument follows from that fact, e.g. (where ~ is an invalid selector string):

Examples

See some tips and tricks in the wiki.

Adapted from example_test.go:

package main

import (
  "fmt"
  "log"
  "net/http"

  "github.com/PuerkitoBio/goquery"
)

func ExampleScrape() {
  // Request the HTML page.
  res, err := http.Get("http://metalsucks.net")
  if err != nil {
    log.Fatal(err)
  }
  defer res.Body.Close()
  if res.StatusCode != 200 {
    log.Fatalf("status code error: %d %s", res.StatusCode, res.Status)
  }

  // Load the HTML document
  doc, err := goquery.NewDocumentFromReader(res.Body)
  if err != nil {
    log.Fatal(err)
  }

  // Find the review items
  doc.Find(".left-content article .post-title").Each(func(i int, s *goquery.Selection) {
		// For each item found, get the title
		title := s.Find("a").Text()
		fmt.Printf("Review %d: %s\n", i, title)
	})
}

func main() {
  ExampleScrape()
}

Support

There are a number of ways you can support the project:

Buy Me A Coffee

License

The BSD 3-Clause license, the same as the Go language. Cascadia's license is here.

goquery (PuerkitoBio/goquery)

parsing
Searching Database…

15K ·GitHub
Goquery
What is this?goquery is a Go library that brings jQuery-like syntax and features to HTML parsing and manipulation, built on Go's net/html package and the cascadia CSS selector library.
If I already know jQuery, will this feel familiar?Very familiar: the function names and the chainable interface follow jQuery wherever possible. The difference is that stateful helpers like height(), css() and detach() are left off, because net/html returns nodes rather than a full-featured DOM tree.
How do I add it to my project?Run 'go get github.com/PuerkitoBio/goquery', import the package, and wrap your HTML in a Document — for example with NewDocumentFromReader — then start selecting with Find().
Which Go version do I need?goquery v1.12.0 and newer require Go 1.25+; older release lines needed Go 1.24+, 1.23+ or 1.18+, and versions before v1.9 worked back to Go 1.1.
Will it parse any HTML I throw at it?Only UTF-8: the underlying net/html parser requires UTF-8 encoding, so making sure the source document provides UTF-8 HTML is the caller's responsibility; the wiki lists ways to handle that.
Where does it run?It is a Go library, not a standalone app: you link it into any Go program, wherever Go compiles.
Why did the author model the API on jQuery instead of designing something new?Because jQuery is ultra-popular, the author felt a similar HTML-manipulating library was better off following its API than starting anew — in the same spirit as Go's fmt package — even keeping some of its less intuitive methods like index().
Why do some methods have names like PrevFiltered or FilterNodes?Go is statically typed, so instead of jQuery's many overloads packed into one variadic method, each variant gets a suffix: XxxFiltered takes a selector string, XxxSelection a Selection, XxxNodes DOM elements, XxxFunction a function, and XxxMatcher a compiled matcher.
Do all jQuery selectors behave the same in goquery?Not exactly: cascadia's selectors do not necessarily match all jQuery (Sizzle) selectors and work more like the DOM's querySelectorAll, with no contextual matching. Invalid selector strings silently compile to a Matcher that matches nothing, so Find('~') just returns an empty selection.
Is the API stable, and is the project still maintained?Yes — the README states the API is stable and will not break. Development is active: v1.13.0 from August 2026 added performance improvements, a top-level Text function with options similar to BeautifulSoup's gettext, and go1.27 to the test matrix.
What are similar projects?cheerio, gjson, jsoup, go, colly, REDox, scrapy, webmagic
Which topics is it in?encoding, golang-library, data-extraction, jquery, parsing, scraping, dom, parser, web-scraping, bsd, css, backend
Creator
PuerkitoBio
Size
0.7 MB
Stars
15K
Updated
CommitOct 12Releasev1.13.0Aug 27
Age
14y
Commits · 90 Days