Pandas · Function

pd.read_html

Reads HTML tables from a URL, path, file-like object, or HTML string and returns a list of pandas DataFrames. Tables can be selected by matching text or HTML attributes.

How it works

The function locates HTML <table> elements in a URL, path, file-like object, or HTML string, then converts matching tables into DataFrames. Use match or attrs to narrow selection and flavor to choose the parsing backend; the result is always a list.

Syntax

pandas.read_html(io, *, match='. +', flavor=None, header=None, index_col=None, skiprows=None, attrs=None, parse_dates=False, thousands=',', encoding=None, decimal='.', converters=None, na_values=None, keep_default_na=True, displayed_only=True, extract_links=None, dtype_backend=<no_default>, storage_options=None)

Parameters

Name	Type	Description
`io`	`str, path object, or file-like object`	URL, path-like object, file-like object, or raw HTML input to parse.
`match`	`str or compiled regular expression, optional`	Regular expression or string used to select tables by their text content.
`flavor`	`{"lxml", "html5lib", "bs4"} or list-like, optional`	HTML parsing engine or ordered collection of engines.
`header`	`int or list-like, optional`	Row labels or levels to use as column headers.
`index_col`	`int or list-like, optional`	Column or columns to use as the DataFrame index.
`skiprows`	`int, list-like, or slice, optional`	Rows to skip before parsing.
`attrs`	`dict, optional`	HTML attributes used to identify target tables.
`parse_dates`	`bool, optional`	Whether to parse date-like values.
`thousands`	`str, optional`	Thousands separator used when converting numeric text.
`encoding`	`str, optional`	Text encoding for the input.
`decimal`	`str, optional`	Decimal separator used when converting numeric text.
`converters`	`dict, optional`	Column-specific conversion functions.

Returns

list of DataFrame objects

Key points

Use pandas.read_html when tabular data is embedded in HTML and the desired result is pandas DataFrames.
Only HTML table elements are candidates; ordinary page text or non-table markup is not directly converted.
Each discovered table becomes a DataFrame whose structure comes from the table's rows and columns.
The source can be remote, local, or already loaded HTML, which supports both ingestion and testing workflows.
Use match with a string or compiled regular expression to restrict parsing to tables containing selected text.
The flavor argument controls which supported HTML parsing backend is used.

Common mistakes

Handle the result as a list even when the input contains only one table; an empty list is generally not the failure behavior.
Install a supported HTML parser before calling the function; parsing cannot proceed without one.
The default match pattern may be too broad or ineffective for realistic pages, so provide a meaningful regular expression or string.

Example: Read a matching HTML table

import pandas as pd

html = """
<table>
  <tr><th>name</th><th>score</th></tr>
  <tr><td>Ada</td><td>95</td></tr>
</table>
"""

tables = pd.read_html(html, match="score")
df = tables[0]
print(df)

Parses the matching HTML table and accesses the first DataFrame in the returned list.

When to use it

Web and report ingestion

Extract structured tables from web pages or saved HTML reports.

Targeted table selection

Parse a known table among multiple tables by matching its text.

Programmatic HTML parsing

Load HTML fixtures into DataFrames for tests and data pipelines.

Interview questions

QWhat does pandas.read_html return?

It returns a list of DataFrame objects, not a single DataFrame. This remains true when the HTML contains only one table.

Follow-up: How would you select one table from a page with several? Use match to filter by table text or attrs to match HTML attributes, then select the desired list element.

QWhat inputs can read_html accept?

io may be a URL, path-like value, file-like object, or raw HTML string. The function searches the HTML for table elements and parses their rows and columns.

Follow-up: What if the source is already an open stream? Pass a file-like object implementing a string read() method.

QHow does the flavor parameter work?

flavor selects the parsing engine and can be one engine or a list-like collection of engines. Supported choices are lxml, html5lib, and bs4.

Follow-up: Why might a list of engines be useful? It permits the parser selection to be supplied as alternatives rather than a single fixed backend.

pandas.DataFrame
pandas.read_csv
pandas.DataFrame.to_html

Source: pandas.read_html — pandas 3.0.6 documentation. Checked 2026-10-15.