NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI · #1094 most downloaded on PyPI
Pytest Snapshot Test Utility
Last release 21 days ago
13 Sep 2026
Release timing varies
gaps range from 8 days to 6 months
Nearly every release is documented
notes for 60 of the last 60 stable releases
2 versions withdrawn
withdrawn after publishing
7 years old
131 releases · first in 2019
Nothing published for this version
Note: 6.1.0 was skipped due to a CI issue. Use 6.1.1 .
Note: 6.1.0 was skipped due to a CI issue. Use 6.1.1.
--snapshot-file-lock for pytest-xdist--snapshot-update under pytest-xdist can race when multiple workers rewrite the same multi-entry amber (.ambr) file, silently dropping snapshots (#1237).
This release adds an experimental opt-in:
--snapshot-file-lock — exclusive file lock + atomic replace around amber writes--snapshot-file-lock-timeout — max wait for the lock (default 60s)Same-machine workers only; not reliable across remote workers / NFS. See #1239.
Callout for pytest-xdist users: please try
--snapshot-file-lockwith--snapshot-updateand open an issue if you hit problems. Locking is expected to become the default in a future minor release.
Full Changelog: v6.0.0...v6.1.1
One column per quarter.
Syrupy 6 focuses on better built-in serialization, clearer snapshot workflows, and large-suite performance. Please review the breaking changes before…
(2026-08-22)
Syrupy 6 focuses on better built-in serialization, clearer snapshot workflows, and large-suite performance. Please review the breaking changes before upgrading.
Most suites should not need significant snapshot updates on upgrade — the main exception is dataclass usage (see below). Syrupy v6 does not change the required Python version or other package dependencies. Support for Python 3.10 will instead be dropped in the next Syrupy major version (v7).
Full Changelog: v5.5.3...v6.0.0
DataclassPlugin)stdlib dataclasses are now serialized natively by the Amber serializer. The separate DataclassPlugin has been removed.
DataclassPlugin: remove imports and plugin wiring. Behavior should match what the plugin produced; no snapshot rewrite should be needed for the dataclass shape itself.repr-style string to structured Amber form (field-by-field). Re-run with --snapshot-update where those assertions fail.Example of what to remove:
# Before (v5)
from syrupy.extensions.amber.dataclasses_plugin import DataclassPlugin
class MySerializer(AmberDataSerializer):
serializer_plugins = [DataclassPlugin, ...]# After (v6) — dataclasses work with the default Amber extension
assert MyDataclass(...) == snapshotAttrs and Pydantic models are unchanged and still need their serializer plugins. See the serializer plugins example.
datetime.date snapshotsThe JSON extension now serializes datetime.date as YYYY-MM-DD instead of a repr string. Existing JSON snapshots that contain dates will need an update.
path_value nested path replacement in default (literal) modepath_value(..., regex=False) now correctly replaces values at nested paths such as user.token. Previously, the default-mode lookup missed escaped path keys, so nested values were left unchanged (and could leak into committed snapshots).
If you relied on the old non-replacement behavior for nested literal paths, or your snapshots still contain values that should have been redacted, expect diffs and re-run with --snapshot-update as needed.
(#1162) — thanks @chuenchen309
Mark snapshot tests with syrupy_snapshot — tests that use the snapshot fixture (directly or indirectly) are marked automatically. Update only those tests with:
pytest --snapshot-update -m syrupy_snapshotIn-memory snapshot diffs — snapshot(diff=...) accepts an in-memory baseline object (not only a snapshot index/name), so you can diff against data already in the test without writing a separate base snapshot.
--snapshot-declaration-order (experimental) — write Amber snapshots in pytest collection/declaration order (including parametrize/ids order) instead of alphabetical snapshot name order.
--snapshot-disable-unused — escape hatch to skip unused-snapshot discovery/reporting/deletion for very large Amber suites where unused detection dominates runtime. Prefer --snapshot-warn-unused when you still want unused counted.
(#1223)
Deterministic set/dict serialization for partial-order elements — sorting no longer depends on PYTHONHASHSEED for values like homogeneous frozensets (partial order under <), which previously caused flaky snapshots.
(#1159) — thanks @chuenchen309
Preserve skipped single-file snapshots — skipped sibling single-file snapshots are no longer reported as unused or deleted under --snapshot-update.
JSON datetime.date serialization — dates serialize as ISO dates instead of repr strings.
(#1216) — thanks @danielnehrig
Improve memory for single-file snapshots — single-file extensions write updates immediately instead of buffering large payloads (e.g. images) until session end. Multi-entry Amber files still batch writes so each .ambr is rewritten once.
Faster unused-snapshot matching on partial selection — unused detection only considers plausible test files, which greatly reduces cost under sharding plugins (e.g. pytest-split).
(#1207, closes #1193) — thanks @tiagoskaneta
Compress xdist snapshot reports — worker→controller snapshot collection payloads are compressed, cutting transfer size for large suites.
Thank you to everyone who contributed to this release:
path_value matcher fix (first contribution)snapshot(diff=...) baselines; syrupy_snapshot marker (first contribution)datetime.date serializationThis release has no functional changes. It just fixes an issue where the release tag pointed to the previous commit instead of the commit with the upd
This release has no functional changes. It just fixes an issue where the release tag pointed to the previous commit instead of the commit with the updated pyproject.toml (see #1144).
Full Changelog: v5.5.2...v5.5.3
fix: Fix detecting pytest-xdist when loaded via PYTEST_PLUGINS by @mgorny in #1142
fix: Defer registering pytest-xdist hook pytest_testnodedown to avoid "unknown hook" error by @edgarrmondragon in #1140
pytest-xdist hook pytest_testnodedown to avoid "unknown hook" error by @edgarrmondragon in #1140Full Changelog: v5.5.0...v5.5.1
feat: detect unused snapshots under pytest-xdist by @frenck in #1132
NOTE: Test suites using pytest-xdist that previously passed due to incomplete snapshot support may now fail if unused snapshots are detected. You can use
--snapshot-warn-unusedto downgrade unused snapshot detection from an error to a warning though it's not recommended.
Full Changelog: v5.4.0...v5.5.0
feat: add --snapshot-no-cleanup to keep unused snapshots on update by @frenck in #1126
Full Changelog: v5.3.4...v5.4.0
perf: drop per-node kwargs dict from the amber serializer by @frenck in #1122
perf: speed up string serialization in amber serializer by @frenck in #1118
Full Changelog: v5.3.2...v5.3.3
fix: overlapping test filenames across directories by @noahnu in #1104
Full Changelog: v5.3.1...v5.3.2
fix(test): mark pydantic and attrs as dependencies for running internal tests by @noahnu in #1108 -- This only affects users trying to run the syrupy
Full Changelog: v5.3.0...v5.3.1
feat: add --snapshot-update-new-only flag (#843) by @SAY-5 in https://github.com/syrupy-project/syrupy/pull/1098
Full Changelog: https://github.com/syrupy-project/syrupy/compare/v5.2.0...v5.3.0
chore(deps): update actions/checkout action to v6.0.2 by @renovate[bot] in https://github.com/syrupy-project/syrupy/pull/1065
Full Changelog: https://github.com/syrupy-project/syrupy/compare/v5.1.0...v5.2.0
add serializer plugin system; plugins for data models
This release introduces new features, bug fixes, and a major license change. It also includes several breaking changes, so please review those careful…
(2025-09-28)
This release introduces new features, bug fixes, and a major license change. It also includes several breaking changes, so please review those carefully before upgrading.
--snapshot-dirname option: A new option, --snapshot-dirname, is now available to change the default directory snapshots are stored in. ([#810](https://github.com/syrupy-project/syrupy/issues/810))xdist workers: Resolves an issue where the terminal summary was not displayed correctly with xdist workers. ([#978](https://github.com/syrupy-project/syrupy/issues/978))pytest_assertrepr_compare hook is called first: This change ensures that Syrupy's assertion hook takes precedence, improving compatibility with other plugins. ([#984](https://github.com/syrupy-project/syrupy/issues/984))License change: The project has switched to the more permissive MIT license. This change applies to all versions from 5.0.0 and beyond. If you need to use the previous Apache 2.0 license, you must continue to use Syrupy versions 4.x or earlier. ([#945](https://github.com/syrupy-project/syrupy/issues/945))
Python and pytest version requirements: Syrupy now requires Python 3.10 or higher. Support for Python 3.8 has been dropped as it reached its end of life in October 2024. The minimum required version of pytest is v8. ([#904](https://github.com/syrupy-project/syrupy/issues/904), [#1024](https://github.com/syrupy-project/syrupy/issues/1024))
Method and constant name changes: Several methods and constants have been renamed for improved clarity and to align with public API standards.
SnapshotCollectionStorage
_read_snapshot_collection -> read_snapshot_collection_read_snapshot_data_from_location -> read_snapshot_data_from_location_write_snapshot_collection -> write_snapshot_collection_get_file_basename -> get_file_basename_file_extension -> file_extensionAmberDataSerializer
_snapshot_sort_key -> snapshot_sort_keyConstants
SNAPSHOT_EMPTY_FOSSIL_KEY -> SNAPSHOT_EMPTY_COLLECTION_KEYSNAPSHOT_UNKNOWN_FOSSIL_KEY -> SNAPSHOT_UNKNOWN_COLLECTION_KEYSNAPSHOT_DIRNAME has been removed in favour of the property on the SnapshotCollectionStorage class and associated CLI option.Full Changelog: https://github.com/syrupy-project/syrupy/compare/v4.9.1...v5.0.0
serializer: preserve trailing newlines in ambr serialization
serializer: raise TypeError when serializing non-byte like object in binary mode
snapshots of deselected parametrized tests wrongly marked as unused
avoid unnecessary env updates to reduce chances of segfault
check current session's pending-write queue when recalling snapshots (e.g. diffing)
# 4.8.0 (2024-11-23) ### Features * add option to disable diffing
allow snapshot dir to be different
pytest-rerunfailures compatibility
feat: Added a new CLI flag: --snapshot-patch-pycharm-diff by @UltimateLobster in https://github.com/syrupy-project/syrupy/pull/864
Full Changelog: https://github.com/syrupy-project/syrupy/compare/v4.6.4...v4.7.0
relax python version constraint, remove upperbound
ignore unused snapshots for skipped test
## 4.6.2 (2024-08-21) ### Bug Fixes * update classifiers, metadata
## 4.6.1 (2024-02-07) ### Bug Fixes * support pytest 8
serializer: add support for FunctionType serialization
# 4.5.0 (2023-09-01) ### Features * support setting defaults
filter: add paths_include filter
add include option to snapshots, similar to exclude
## 4.2.2 (2023-08-28) ### Bug Fixes * remove colored dependency
## 4.2.1 (2023-08-21) ### Bug Fixes * support python 3.12
serializer: add snapshot regex value matcher and bypass custom repr helper
preserve Falsy values in assertion diff function
amber: expose serialize_custom_iterable method of AmberDataSerializer
diffing excessively large snapshot lines
large snapshot diff recursion error
improve reporting around xfailed snapshots, close #736
## 4.0.5 (2023-07-04) ### Bug Fixes * hide empty snapshot report
incorrect marking of TestClass.test_method as unused, close #717
support colored >=1.5.0 dependency, close #758
defer snapshot default extension import (#734) (dfd5910), closes #719
serializer: handling of multi-part file extensions in SingleFileExtension
Serializers may now throw a TaintedSnapshotError which will tell the user to regenerate the snapshot even if the underlying data has not changed. This is to support rolling out more subtle changes to the serializers, such as the introduction of serializer metadata.
Renamed DataSerializer to AmberDataSerializer.
serializer: Key order is now preserved if using OrderedDict in both the Amber serializer and JSON serializer.
json: The JSONSnapshotExtension now serializes Python's None as "null" rather than "None".
Raise minimum python version to 3.8.1 and min. pytest version to v7.
PyTestLocation.filename has been renamed to .basename
refactor: add test_location kwarg to get_snapshot_name
refactor: get_snapshot_name is now static as a classmethod
refactor: remove pre and post read/write hooks
Pre and post read/write hooks have been removed without replacement to make internal refactor simpler. Please open a GitHub issue if you have a use case for these hooks.
refactor: rename Fossil to Collection
The term 'fossil' has been replaced by the clearer term 'collection'.
refactor: pass test_location to read_snapshot
refactor: remove singular write_snapshot method
refactor: dirname property to method
refactor: pass test_location to discover_snapshots
refactor: remove usage of self.test_location
refactor: make write_snapshot a classmethod
refactor: do not instantiate extension with test_location
Numerous instance methods have been refactored as classmethods.
…consider backporting critical bugs and security vulnerabilities on request (create a GitHub issue).
NOTE: You will need to regenerate snapshots if using the default Amber serializer. Run
pytest --snapshot-update.
null. (#622)pytest --snapshot-update. This version marker is being placed to make it simpler to support multiple versions of the amber serializer, and thus rollout what has previously been considered breaking changes, without queueing for a major version update.ensure all pytest options are serializable
only instantiate colored objects if color is not disabled
## 3.0.4 (2022-11-03) ### Bug Fixes * update poetry build backend
use more expressive glob when building whl
update classifiers (no material change)
avoid reporting crash for snapshot dir outside pytest dir
Drop Python 3.6 support due to end of life.
ignore test_a_suffix snapshots when running test_a
Migration Guide
pytest --snapshot-update to regenerate amber snapshotsprovide __repr__ for SnapshotAssertion
# 2.2.0 (2022-05-12) ### Features * support snapshots in doc tests
# 2.1.0 (2022-05-11) ### Features * add snapshot diffing support
amber: change serialization to be py syntax like
## 1.7.4 (2022-02-16) ### Bug Fixes * support pytest 7
Your coding agent can read these notes before it upgrades. Set up the MCP server →