---
id: pytest-github-actions-annotate-failures
version: "0.4.2"
license: MIT
license_treatment: permissive
maintenance: active
---

# pytest-github-actions-annotate-failures — pytest plugin to annotate failed tests with a workflow command for GitHub Actions

License: permissive · Maintenance: active · Downloads: 3.7M/mo

## What it is and what it does

This is a pytest plugin designed to integrate test results directly into GitHub Actions workflows. When tests fail, it uses GitHub Actions workflow commands to create annotations that appear in the Actions UI, pull request checks, and job summaries, making failures immediately visible without requiring developers to dig through logs.

The plugin works by hooking into pytest's test execution and capturing failures, then emitting GitHub workflow annotation commands that the Actions runner interprets. It requires only pytest as a runtime dependency and has low install friction. It supports warning annotations when used with Pytest 6.0 or later, and can be disabled with a command-line flag if needed. For Docker-based test runs or tests in repository subdirectories, environment variables must be configured to ensure GitHub correctly maps reported failures to source files.

Use it for:

- Automatically surface test failures in GitHub Actions job summaries and PR checks without manual log parsing
- Integrate pytest test results into GitHub's native CI/CD UI for faster failure identification
- Annotate both test failures and warnings in GitHub Actions workflows with a single plugin install
- Run tests in Docker containers within GitHub Actions while preserving failure annotations via environment variable configuration

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

A pytest plugin that automatically annotates failed tests in GitHub Actions workflows using GitHub's workflow annotation commands, making test failures visible directly in the Actions UI.

Yes. This plugin is actively maintained, has no known vulnerabilities, carries a permissive MIT license, and solves a real workflow problem—making test failures visible in GitHub Actions without extra configuration. Install it if you run pytest in GitHub Actions and want failures to surface directly in the UI.

## Install

pip install pytest-github-actions-annotate-failures
uv add pytest-github-actions-annotate-failures
poetry add pytest-github-actions-annotate-failures

## Installing pytest-github-actions-annotate-failures

Before you install: Low install friction with a single runtime dependency on pytest. Actively maintained with a recent release; last commit on 2026-08-13 and marked as Production/Stable.

License in practice: MIT license permits free use, modification, and distribution with minimal restrictions, making it straightforward to integrate into any project.

Quickstart:

pip install pytest-github-actions-annotate-failures
pytest

# In GitHub Actions workflow:
- run: pytest

Requires Python 3.10 or later. When running tests in Docker, the GITHUB_ACTIONS environment variable must be manually set to true. If tests run from a subdirectory, PYTEST_RUN_PATH must be set to the relative path for correct file identification.

Verify before relying:

- Whether warning annotations (available with Pytest 6.0+) work correctly with all current pytest versions
- Performance impact when handling large numbers of test failures in a single run

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 3.7M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

pytest github actions integration, github actions test failure annotations, pytest workflow command plugin, ci/cd test reporting github, pytest github actions plugin, test failure annotations ci, github actions pytest reporting, github-actions, ci-cd, test-reporting

[View on SkillFed](https://skillfed.io/packages/pytest-github-actions-annotate-failures) · [View on PyPI](https://pypi.org/project/pytest-github-actions-annotate-failures/)