BeautifulSoup tutorial: Scraping web pages with Python

25 March 2021 | 7 min read

In this article, we will see how to extract structured information from web-page leveraging BeautifulSoup and CSS selectors.

WebScraping with BeautifulSoup

Pulling the HTML out

BeautifulSoup is not a web scraping library per se. It is a library that allows you to efficiently and easily pull out information from HTML. In the real world, it is often used for web scraping projects.

So, to begin, we'll need HTML. We will pull out HTML from the HackerNews landing page using the requests python package.

import requests
response = requests.get("")
if response.status_code != 200:
	print("Error fetching page")
	content = response.content

> b'<html op="news"><head><meta name="referrer" content="origin"><meta name="viewport" 
> content="width=device-width, initial-scale=1.0"><link rel="stylesheet" type="text/css" href="news.css? ...

Parsing the HTML with BeautifulSoup

Now that the HTML is accessible we will use BeautifulSoup to parse it. If you haven't already, you can install the package by doing a simple pip install beautifullsoup4. In the rest of this article, we will refer to BeautifulSoup4 as BS4.

We now need to parse the HTML and load it into a BS4 structure.

from bs4 import BeautifulSoup
soup = BeautifulSoup(response.content, 'html.parser')

This soup object is very handy and allows us to easily access many useful pieces of information such as:

# The HTML title of the page
> <title>Hacker News</title>

# The test title of the page
> Hacker News

# All links in the page
nb_links = len(soup.find_all('a'))
print(f"There are {nb_links} links in this page")
> There are 231 links in this page

# Text from the page
> Hacker News
> Hacker News
> new | past | comments | ask | show | jobs | submit
> login
> ...

Targeting DOM elements

You might begin to see a pattern in how to use this library. It allows you to quickly and elegantly target the DOM elements you need.

If you need to select DOM elements from its tag (<p>, <a>, <span>, ....) you can simply do soup.<tag> to select it. The caveat is that it will only select the first HTML element with that tag.

For example if I want the first link I just have to do

 first_link = soup.a
 ><a href=""><img height="18" src="y18.gif" style="border:1px white solid;" width="18"/></a>

This element will also have many useful methods to quickly extract information:

# The text of the link
# Empty because first link is an <img>

# The href of the link

This is a simple example. If you want to select the first element based on its id or class it is not much more difficult:

pagespace = soup.find(id="pagespace")
> <tr id="pagespace" style="height:10px" title=""></tr>

# class is a reserved keyword in Python, hence the '_'
athing = soup.find(class_="athing")
> <tr class="athing" id="22115671">
> ...

And if you don't want the first matching element but instead all matching elements, just replace find with find_all.

This simple and elegant interface allows you to quickly write short and powerful Python snippets.

For example, let's say that I want to extract all links in this page and find the top three links that appear the most on the page. All I have to do is this:

from collections import Counter
all_hrefs = [a.get('href') for a in soup.find_all('a')]
top_3_links = Counter(all_hrefs).most_common(3)
> [('from?', 3), ('item?id=22115671', 2), ('item?id=22113827', 2)]

Advanced usage

BeautifulSoup is a great example of a library that is both easy to use and powerful.

You can do much more to select elements using BeautifulSoup. Although we won't cover those cases in this article, here are few examples of advanced things you can do:

We also only covered how to target elements but there is also a whole section about updating and writing HTML. Again, we won't cover this in this article.

Let's now talk about CSS selectors.

CSS selectors

Why learn about CSS selectors if BeautifulSoup can select all elements with its pre-made method?

Well, you'll soon understand.

Hard dom

Sometimes, the HTML document won't have a useful class and id. Selecting elements with BS4 without relying on that information can be quite verbose.

For example, let's say that you want to extract the score of a post on the HN homepage, but you can't use class name or id in your code. Here is how you could do it:

results = []
all_tr = soup.find_all('tr')
for tr in all_tr:
	if len(tr.contents) == 2:
		if len(tr.contents[0].contents) == 0 and len(tr.contents[1].contents) == 13:
			points = tr.contents[1].text.split(' ')[0].strip()
>['168', '80', '95', '344', '7', '84', '76', '2827', '247', '185', '91', '2025', '482', '68', '47', '37', '6', '89', '32', '17', '47', '1449', '25', '73', '35', '463', '44', '329', '738', '17']

Not that great right?

If you rely on CSS selectors, it becomes easier.

all_results ='td:nth-child(2) > span:nth-child(1)')
results = [r.text.split(' ')[0].strip() for r in all_results]

>['168', '80', '95', '344', '7', '84', '76', '2827', '247', '185', '91', '2025', '482', '68', '47', '37', '6', '89', '32', '17', '47', '1449', '25', '73', '35', '463', '44', '329', '738', '17']

This is much clearer and simpler, right? Of course, this example artificially highlights the usefulness of the CSS selector. But, you will quickly see that the DOM structure of a page is more reliable than the class name.

Easily debuggable

Another thing that makes CSS selectors great for web scraping is that they are easily debuggable. I'll show you how. Open Chrome, then open your developers' tools, (left-click -> "Inspect"), click on the document panel, and use "Ctrl-F or CMD-F" to be in search mode.

In the search bar, you'll be able to write any CSS expression you want, and Chrome will instantly find all elements matching it.

Iterate over the results by pressing Enter to check that you are correctly getting everything you need.

Hacker News's HTML

What is great with Chrome is that it works the other way around too. You can also left-click on an element, click "Copy -> Copy Selector", and your selector will be pasted in your clipboard.

Chrome Dev Tools XPath selector


CSS selectors, and particularly pseudo-classes, allow you to select any elements you want with one simple string.

Child and descendants

You can select direct child and descendant with:

# all <p> directly inside and <a>
a > p

# all <p> descendant of an <a>
a p

And you can mix them together:

a > p > .test .example > span

This will totally work.


This one is one of my favorites because it allows you to select elements based on the elements on the same level in the DOM hierarchy, hence the sibling expression.

#html example
	<p>This paragraph will be selected</p> (match h2 ~ p / h2 + p)
	<p>This paragraph will be selected</p> (match h2 ~ p)

To select all p coming after an h2 you can use the h2 ~ p selector (it will match two p). You can also use h2 + p if you only want to select p coming directly after an h2 (it will match only one p)

Attribute selectors

Attribute selectors allow you to select elements with particular attributes values. So, p[data-test="foo"] will match

<p data-test="foo"></p>

Position pseudo classes

If you want to select the last p inside a section, you can also do it in "pure" CSS by leveraging position pseudo-classes. For this particular example, you just need this selector: section p:last-child(). If you want to learn more about this, I suggest you take a look at this article

Maintainable code

I also think that CSS expressions are easier to maintain. For example, at ScrapingBee, when we do custom web scraping tasks all of our scripts begins like this:

	SCORE_SELECTOR = "td:nth-child(2) > span:nth-child(1)"

This makes it easy and quick to fix scripts when DOM changes appear. The laziest way to do it is to simply copy/paste what Chrome gives you when you left-click on an element. If you do this, be careful, Chrome tends to add a lot of useless selectors when you use this trick. So do not hesitate to clean them up a bit before using them in your script.

💡 We released a new feature that makes this whole process way simpler. You can now extract data from HTML with one simple API call. Feel free to check the documentation here.


In the end, everything you do with pure CSS selectors you can do it with BeautifulSoup4. But, I think choosing the former is the best way to go.

I hoped you liked this article about web scraping in Python and that it will make your life easier.

If you'd like to read more about web scraping in Python do not hesitate to check out our extensive Python web scraping guide.

You might also be interested by our XPath tutorial

Happy Scraping,

Pierre de Wulf

image description
Pierre de Wulf

Pierre is a data engineer who worked in several high-growth startups before co-founding ScrapingBee. He is an expert in data processing and web scraping.