---
id: pyhamcrest
version: "2.1.0"
license: BSD License Copyright 2020 hamcrest.org All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are… (full text in the JSON record)
license_treatment: permissive
maintenance: aging
---

# PyHamcrest — Hamcrest framework for matcher objects

License: permissive · Maintenance: aging · Downloads: 6.4M/mo

## What it is and what it does

PyHamcrest is a matcher framework that lets you write test assertions as declarative rules rather than imperative comparisons. Instead of writing brittle equality checks, you compose matchers to express exactly what aspect of an object you're testing and to what precision. This helps tests stay readable and maintainable: they fail when behavior deviates from expectations but pass through minor, unrelated changes.

The library comes with matchers for objects, numbers, text, sequences, dictionaries, and logical combinations. You can also write custom matchers by subclassing BaseMatcher. PyHamcrest integrates naturally with unittest and other test frameworks. It has no runtime dependencies and supports Python 3.6 and later across CPython, PyPy, and Jython.

Use it for:

- Write unit tests with readable, composable assertions that fail precisely when behavior changes.
- Validate UI or form input by matching against patterns for strings and regular expressions.
- Filter or validate data structures using reusable matcher logic across multiple test cases.
- Create custom matchers for domain-specific validation rules to eliminate test code duplication.
- Build flexible test suites that distinguish between critical behavior changes and minor implementation details.

## Worth the install?

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

PyHamcrest provides a framework for writing declarative matcher objects that enable flexible, readable assertions in unit tests and data validation scenarios.

Yes. PyHamcrest is stable (Production/Stable status), widely used (6393524 monthly downloads), has no dependencies, and carries a permissive BSD License. The aging maintenance status (last release 2023-10-22) is not a blocker for a mature, focused library—it indicates stability rather than abandonment. Install it if you want more readable, maintainable test assertions.

## Install

pip install pyhamcrest
uv add pyhamcrest
poetry add pyhamcrest

## Installing PyHamcrest

Before you install: Low install friction with no runtime dependencies. Maintenance status is aging—last release was 2023-10-22 and last commit 2026-02-12, but the repository remains active and not archived.

License in practice: BSD License (permissive). You can use, modify, and distribute PyHamcrest freely in commercial and private projects, provided you retain the copyright notice and disclaimer.

Quickstart:

pip install PyHamcrest

from PyHamcrest import assert_that, equal_to
import unittest

class MyTest(unittest.TestCase):
    def test_example(self):
        assert_that(5, equal_to(5))

Verify before relying:

- Whether the import path is 'hamcrest' or 'PyHamcrest' in current versions

## Package facts

- License: BSD License Copyright 2020 hamcrest.org All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are… (full text in the JSON record) (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: aging
- Downloads: 6.4M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

matcher framework for testing, flexible test assertions, hamcrest matchers python, readable unit test assertions, composable test matchers, data validation matchers, test assertion library, testing, matchers, assertions

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