Guide · Open source

How to use jsoup: parse, select and clean HTML in Java

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

jsoup is a Java library for working with real-world HTML and XML. It can fetch a page from a URL, read HTML from a file or string, search it with CSS selectors or DOM methods, edit the markup, and clean untrusted HTML against a safelist. This guide is for Java developers who want to get a first working example running and understand the main pieces.

jsoupjhy/jsoup · ★ 11.4k · MIT Install options & downloads

Quick start

1Add the dependency. Add the jsoup Maven or Gradle dependency to your build, or download the jar from jsoup.org.
2Read the cookbook introduction. Open the cookbook introduction at jsoup.org to see how parsing is documented.
3Fetch or load HTML. Use Jsoup.connect(url).get() for a live page, or parse a string or file.
4Select elements. Call select() with a CSS selector and loop over the returned Elements.
5Read attributes and text. Use attr() and absUrl() to read values from each element.
6Clean user HTML. Pass untrusted HTML through the safelist sanitizer before storing or displaying it.

Install jsoup with Maven or Gradle

The simplest way to add jsoup is through your build tool. The README gives a Maven dependency and a Gradle dependency. You can also download the jsoup jar from the project website and add it to your project manually.

Java is required, but the README does not state which Java version is needed. If you use jsoup in an Android project, the README says core library desugaring with the NIO specification should be enabled to support Java 8+ features.

Maven: add the org.jsoup:jsoup dependency to your pom.xml.
Gradle: add implementation 'org.jsoup:jsoup' with the version shown in the README.
Manual: download the jar from jsoup.org and put it on your classpath.

<dependency>
  <!-- jsoup HTML parser library @ https://jsoup.org/ -->
  <groupId>org.jsoup</groupId>
  <artifactId>jsoup</artifactId>
  <version>1.23.2</version>
</dependency>

Fetch a page or parse HTML from a file or string

The entry point is the Jsoup class. Jsoup.connect(url).get() fetches a page from a URL and returns a Document. The cookbook also covers parsing a document from a string and from a file, so you can work with HTML you already have.

Because jsoup parses HTML the same way modern browsers do, messy markup still produces a usable tree you can query.

From a URL: Jsoup.connect(url).get()
From a string or file: see the cookbook pages on parsing input (linked at jsoup.org).

Document doc = Jsoup.connect("https://en.wikipedia.org/").get();
log(doc.title());

Select elements with CSS selectors

Once you have a Document, call select() with a CSS selector to get an Elements list. You can loop over the results and read attributes or text. The README also mentions DOM traversal and XPath-style selection as options, and the selector syntax is documented in the cookbook.

The example below selects links inside a specific section of the Wikipedia homepage and prints each link's title and absolute URL.

Use doc.select("selector") to get matching elements.
Use attr("name") to read an attribute.
Use absUrl("href") to get a full URL for a relative link.

Elements newsHeadlines = doc.select("#mp-itn b a");
for (Element headline : newsHeadlines) {
    log("%s\n\t%s",
        headline.attr("title"), headline.absUrl("href"));
}

Edit HTML, attributes and text

jsoup can also change the HTML it parses. The README lists manipulating HTML elements, attributes, and text as a core feature, and the cookbook has pages on setting HTML. You can use this to tidy markup or update content inside a Java application.

When you are done editing, the README lists outputting tidy HTML as a feature, via the html() method on Element.

Change element content, attributes and text using the DOM-style methods in the API.
Output cleaned markup with the html() method on Element.

Clean untrusted HTML to help prevent XSS

If your backend accepts HTML from users, jsoup can clean it against a safelist. The README describes this as a way to help prevent XSS attacks. Only the tags and attributes allowed by the safelist are kept.

Check the cookbook page on the safelist sanitizer for the exact API and the available safelists before using it in production.

Cleaning is done against a safelist, not a blocklist.
The README says this helps prevent XSS; it is not a complete security guarantee on its own.

What people use it for

Pull headlines or links from a public web page into a Java application.
Extract product or article fields from HTML pages using CSS selectors.
Sanitize comments or rich-text input submitted by users before saving it.
Tidy or edit HTML templates inside a Java backend.

Frequently asked questions

Is jsoup free to use?

jsoup is distributed under the MIT license, which the README describes as a liberal open source license. The source code is on GitHub. Check the license page at jsoup.org for the full terms.

What do I need to install jsoup?

You need Java and either Maven, Gradle, or a downloaded jsoup jar. The README does not specify a minimum Java version, so check the project documentation before you start.

Can jsoup run JavaScript on a page?

No. The README describes jsoup as an HTML parser, not a browser. Pages that depend heavily on JavaScript to render their content may not contain the data you need in the fetched HTML.

Does jsoup support XPath?

The README says jsoup supports DOM API methods, CSS, and XPath selectors. Look at the API documentation for the exact methods.

Is jsoup enough to make user input safe?

jsoup can clean untrusted HTML against a safelist to help prevent XSS attacks. Use the safelist sanitizer as part of a wider security approach rather than relying on it alone.

What are alternatives to jsoup?

Comparable projects mentioned include HtmlUnit, Jericho HTML Parser, Apache Tika, and OWASP Java HTML Sanitizer. HtmlUnit is closer to a full browser, while OWASP Java HTML Sanitizer focuses on cleaning HTML.

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

Choose jsoup if you are a Java developer who needs to scrape, extract, edit or sanitize HTML and already knows CSS selectors. Pick something else if you need a ready-made tool with no coding, a language other than Java, or a browser that runs JavaScript.

Install options & downloads