Skip to content

How to find an HTML element by class with BeautifulSoup

When you already know the class attached to the markup you want, BeautifulSoup lets you target it directly instead of walking the tree node by node.

OUTPUT FORMATSHTMLJSONMarkdown

The key is the attrs parameter on find and find_all: you pass a dictionary whose class key holds the class name you are hunting for. This guide shows the working pattern, explains when to reach for find versus find_all, and covers the two situations that trip most people up — elements carrying several classes, and lookups that quietly return nothing.

The core pattern: attrs with a class key

BeautifulSoup's find and find_all both accept an attrs dictionary that maps attribute names to the values you want. To pull elements sharing a particular class, set the class key to that class name. find stops at the first matching element and returns a single tag object; find_all returns every match as a list. The runnable example below loads a page with requests, parses it with html.parser, then uses find with attrs={"class": "mb-[21px]"} to grab the element carrying that class and prints its .string text.

Choosing between find and find_all

Use find when you expect exactly one element — a page heading, a single price block, a unique call-to-action. Use find_all when the class is reused across a list of cards, rows, or links and you need the whole set. A quick decision checklist:

  • Do you need one value? Use find and read .string or .get_text().
  • Do you need every occurrence? Use find_all and loop over the returned list.
  • Unsure how many exist? Start with find_all, check the length, then decide.

If find returns None, the class was not present in the parsed document — that is a different outcome from an element that exists but has empty text.

The multi-class pitfall

HTML elements often carry more than one class, for example class="card featured". A single-string attrs value matches the class attribute exactly, so a lookup for "card" alone may miss an element whose attribute reads "card featured". When you are dealing with multi-class elements, pass the classes as a list so BeautifulSoup matches on the set rather than the literal string. Always inspect the real markup first — printing the tag's attributes is faster than guessing.

Field and control map

A short map of the moving parts in the example:

  • attrs — the dictionary passed to find/find_all; its class key holds the target class name.
  • find(...) — returns the first matching tag object, or None.
  • find_all(...) — returns a list of matching tag objects, possibly empty.
  • .string — the text content of the matched tag, used in the print step.
  • html.parser — the built-in parser passed to BeautifulSoup in the example.

Keeping these straight makes it easy to adapt the pattern to any class you need.

Related BeautifulSoup questions

If your task moves beyond a single class lookup, these companion questions cover nearby techniques: comparing Scrapy and BeautifulSoup, using XPath selectors, finding all links, finding elements without specific attributes, finding by attribute, finding by multiple tags, locating sibling nodes, scraping tables, and selecting values between two nodes. A longer BeautifulSoup web scraping tutorial is also available for a full walkthrough.

Frequently asked questions

What is the difference between find and find_all when searching by class?

find returns the first element whose class matches and stops there, giving you a single tag object (or None). find_all returns a list of every matching element, which may be empty. Choose find for unique elements and find_all when the class repeats across a list.

Why does my class lookup return None even though the class is in the HTML?

The most common cause is a multi-class attribute. A single-string attrs value matches the class attribute exactly, so an element with class="card featured" will not match a lookup for "card" alone. Pass the classes as a list, or inspect the tag's attributes to confirm the exact value.

Can I get the text of the matched element?

Yes. The matched tag object exposes .string for its text content, as the example does with print(h1.string). For elements containing nested tags, .get_text() is often more reliable because it collects text from descendants too.