pytest-html

4.2.0 verified Tue May 12 auth: no python install: verified

pytest-html is a plugin for the pytest testing framework that generates comprehensive HTML reports for test results. It provides a visual overview of test runs, including pass/fail status, durations, and detailed information for each test. The library is actively maintained, with version 4.2.0 being the current release, and follows a frequent release cadence, addressing bug fixes and improvements regularly.

pip install pytest-html

Common errors

error pytest: error: unrecognized arguments: --html=report.html ↓

cause The 'pytest-html' plugin is not installed in the Python environment where pytest is being run, so pytest does not recognize the `--html` option.

fix

Install the plugin using: pip install pytest-html

error ImportError: cannot import name 'HTMLReport' from 'pytest_html.plugin' ↓

cause Attempting to import an internal class (`HTMLReport`) which is not part of the public API, may have moved, or changed in recent versions of `pytest-html`.

fix

Avoid direct imports of internal modules; instead, use pytest-html's public hooks (e.g., pytest_html_report, pytest_configure) for report customization.

error AttributeError: 'HTMLReport' object has no attribute 'environment' ↓

cause Trying to access or modify the report's environment attributes using an outdated method; the `environment` attribute's structure changed in `pytest-html` v3.0.

fix

Use the pytest_configure hook to add environment information via config._html.environment.add('Key', 'Value') (for pytest-html v3.0+). Example:

# conftest.py
def pytest_configure(config):
    if hasattr(config, '_html'):
        config._html.environment.add('Platform', 'Linux')
        config._html.environment.add('Python Version', '3.9')

error pytest: error: unrecognized arguments: --title="My Test Report" ↓

cause Using an incorrect command-line option (`--title`) instead of the `pytest-html` specific option (`--html-title`) to set the report's title.

fix

Use --html-title to specify the report title: pytest --html=report.html --html-title="My Test Report"

Warnings

breaking Python 3.7 support was dropped in `pytest-html` v4.0.0. Ensure your Python environment is 3.8+ to use versions 4.x.x. ↓

fix Upgrade Python to 3.8 or newer, or downgrade pytest-html to a 3.x.x version.

breaking The `py` module was removed as a dependency in `pytest-html` v4.0.0. If your `conftest.py` or custom plugins directly imported `py` for XML/HTML generation (e.g., `from py.xml import html`), you may need to adjust your code. While `py.xml.html` is still commonly used in examples, its direct dependency on `py` is gone. ↓

fix Remove explicit dependencies on `py` if no longer needed. The `py.xml.html` module is still implicitly available via `pytest-html`'s internal usage or if `pytest` itself provides it, but consider direct HTML string generation for custom content where possible to reduce implicit dependencies.

deprecated Configuration options `duration_formatter` and `render_collapsed = True` were deprecated in v4.0.0. `duration_formatter` has no effect, and `render_collapsed = True` should be replaced with `render_collapsed = all` for consistency with query parameters. ↓

fix Remove `duration_formatter` as it's no longer supported. Update `render_collapsed = True` in your `pytest.ini` or `pyproject.toml` to `render_collapsed = all`.

deprecated The `report.extra` attribute and the `extra` fixture were deprecated in v4.0.0. Use `report.extras` and the `extras` fixture instead for adding custom content to reports. ↓

fix Update your `conftest.py` hooks or test functions to use `report.extras.append(...)` and inject content via the `extras` fixture instead of `extra`.

gotcha When using `--self-contained-html`, images or links added as external resources (e.g., screenshots saved to separate files) may not display correctly as they are not embedded into the report. The plugin will issue a warning. ↓

fix For truly self-contained reports with images, embed images directly into the HTML using base64 encoding if possible, or ensure external image files are bundled and accessible alongside the report.

gotcha Customizing the report table using hooks like `pytest_html_results_table_header` might lead to empty result tables when running tests with tags in `pytest-html` v4.1.1 and v4.2.0 due to the hook not being invoked. ↓

fix This is a known issue (GitHub #849). Check the project's issue tracker for updates. Downgrading to v3.2.0 might temporarily resolve it, or refactor custom column additions to a different hook or mechanism if available.

Install compatibility verified last tested: 2026-05-12 v4.2.0 (up to date)

python os / libc status wheel install import disk mem side effects

3.10 alpine (musl) wheel - 0.00s 32.1M 0.0M clean

3.10 alpine (musl) - - 0.00s 31.9M 0.0M -

3.10 slim (glibc) wheel 3.0s 0.00s 33M 0.0M clean

3.10 slim (glibc) - - 0.00s 32M 0.0M -

3.11 alpine (musl) wheel - 0.00s 35.3M 0.0M clean

3.11 alpine (musl) - - 0.00s 35.1M 0.0M -

3.11 slim (glibc) wheel 2.9s 0.00s 36M 0.0M clean

3.11 slim (glibc) - - 0.00s 36M 0.0M -

3.12 alpine (musl) wheel - 0.00s 26.9M 0.0M clean

3.12 alpine (musl) - - 0.00s 26.7M 0.0M -

3.12 slim (glibc) wheel 2.7s 0.00s 27M 0.0M clean

3.12 slim (glibc) - - 0.00s 27M 0.0M -

3.13 alpine (musl) wheel - 0.00s 26.7M 0.0M clean

3.13 alpine (musl) - - 0.00s 26.3M 0.0M -

3.13 slim (glibc) wheel 2.7s 0.00s 27M 0.0M clean

3.13 slim (glibc) - - 0.00s 27M 0.0M -

3.9 alpine (musl) wheel - 0.00s 31.4M 0.0M clean

3.9 alpine (musl) - - 0.00s 31.2M 0.0M -

3.9 slim (glibc) wheel 3.4s 0.00s 32M 0.0M clean

3.9 slim (glibc) - - 0.00s 32M 0.0M -

Imports

pytest_html
```
import pytest_html
from py.xml import html # For HTML content in hooks
```
pytest-html is primarily used via command-line options or pytest.ini. Direct imports are typically for customizing reports using pytest hooks in 'conftest.py' files, for instance, to add custom content or modify report sections. The `py.xml.html` module is often imported when generating HTML content within these hooks.

Quickstart last tested: 2026-04-24

Create a test file (e.g., `test_example.py`). Run pytest from your terminal, specifying the `--html` option to define the report filename and `--self-contained-html` to embed all CSS/JS directly into the HTML, making it easier to share.

import pytest

# test_example.py
def test_pass():
    assert True

def test_fail():
    assert False

def test_skipped():
    pytest.skip("This test is skipped")

# To run tests and generate a self-contained HTML report:
# $ pytest --html=report.html --self-contained-html
# (Run this command in your terminal where test_example.py is located)