---
id: syrupy
version: "5.5.3"
license: MIT
license_treatment: permissive
maintenance: active
---

# syrupy — Pytest Snapshot Test Utility

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

## What it is and what it does

Syrupy is a pytest plugin that implements snapshot testing—a pattern where test assertions compare computed output against stored reference snapshots to detect regressions. Instead of writing brittle assertions on exact values, you write `assert actual == snapshot`, and syrupy manages the stored snapshots for you. On first run, it fails and prompts you to generate snapshots; on subsequent runs, it compares against those stored files. If output changes, the test fails, alerting you to the difference. You can update snapshots with `pytest --snapshot-update` when changes are intentional.

The plugin is designed around three principles: extensibility (you can add custom serializers for unsupported types), idiomatic pytest style (snapshots work as natural assertions, not special methods), and soundness (tests fail if a snapshot is missing, not just on differences). It supports filtering object attributes via include/exclude functions, customizing serialization through `__repr__` overrides, and integrating with unittest TestCase subclasses through fixtures. Snapshots are stored in a `__snapshots__` directory alongside your tests and should be committed to version control.

Use it for:

- Regression testing of complex data structures, API responses, or rendered output where exact values matter but are hard to predict.
- Validating that refactoring or optimization changes don't alter computed results unexpectedly.
- Testing serialization and deserialization of custom objects by comparing their snapshot representation.
- Detecting unintended changes to generated code, configuration, or formatted output in CI/CD pipelines.
- Documenting expected behavior by storing snapshots as living examples of what your code produces.

## Worth the install?

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

Syrupy is a pytest plugin that enables snapshot testing by letting you assert that computed results remain unchanged across test runs, using simple equality comparisons like `assert actual == snapshot`.

Yes. Syrupy is actively maintained, has no security vulnerabilities, installs with minimal friction, and solves a real testing problem—regression detection on complex outputs. It's well-suited for projects that need to catch subtle changes in computed results. Install it if you're writing tests for data transformations, API responses, or any output where immutability matters but exact assertions are unwieldy.

## Install

pip install syrupy
uv add syrupy
poetry add syrupy

## Installing syrupy

Before you install: Installs with low friction as a pure Python wheel with only pytest as a runtime dependency. Actively maintained with a recent release; compatible with current Python versions (3.10+) and recent pytest versions (8+).

License in practice: MIT license permits free use, modification, and distribution with minimal restrictions, making it suitable for both open-source and proprietary projects.

Quickstart:

pip install syrupy

# In test_example.py:
def test_foo(snapshot):
    actual = "Some computed value!"
    assert actual == snapshot

# Run: pytest --snapshot-update

Requires Python 3.10 or later and pytest 8 or later; snapshot fixture does not work directly in unittest.TestCase subclasses without a workaround.

Verify before relying:

- Performance characteristics when handling very large snapshots or deeply nested object graphs.
- Exact extent of custom serializer extensibility beyond built-in types and __repr__ overrides.

## Package facts

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

## Tags

pytest snapshot testing, snapshot test plugin, assert immutability testing, regression test snapshots, pytest fixture snapshot, golden file testing, output comparison testing, testing-utilities, regression-testing

[View on SkillFed](https://skillfed.io/packages/syrupy) · [View on PyPI](https://pypi.org/project/syrupy/)