Packaging guidelines

Downstream packagers often want to package Hypothesis. Here are some guidelines.

The primary guideline is this: If you are not prepared to keep up with the Hypothesis release schedule, don’t. You will annoy me and are doing your users a disservice.

Hypothesis has a very frequent release schedule. It’s rare that it goes a week without a release, and there are often multiple releases in a given week.

If you are prepared to keep up with this schedule, you might find the rest of this document useful.

Release tarballs

These are available from the GitHub releases page. The tarballs on PyPI are intended for installation from a Python tool such as pip and should not be considered complete releases. Requests to include additional files in them will not be granted. Their absence is not a bug.


Python versions

Hypothesis is designed to work with a range of Python versions - we support all versions of CPython with upstream support. We also support the latest versions of PyPy for Python 3.

Other Python libraries

Hypothesis has mandatory dependencies on the following libraries:

Hypothesis has optional dependencies on the following libraries:

extras_require = {
    "cli": ["click>=7.0", "black>=19.10b0", "rich>=9.0.0"],
    "codemods": ["libcst>=0.3.16"],
    "ghostwriter": ["black>=19.10b0"],
    "pytz": ["pytz>=2014.1"],
    "dateutil": ["python-dateutil>=1.4"],
    "lark": ["lark>=0.10.1"],  # probably still works with old `lark-parser` too
    "numpy": ["numpy>=1.17.3"],  # oldest with wheels for non-EOL Python (for now)
    "pandas": ["pandas>=1.1"],
    "pytest": ["pytest>=4.6"],
    "dpcontracts": ["dpcontracts>=0.4"],
    "redis": ["redis>=3.0.0"],
    "crosshair": ["hypothesis-crosshair>=0.0.4", "crosshair-tool>=0.0.54"],
    # zoneinfo is an odd one: every dependency is conditional, because they're
    # only necessary on old versions of Python or Windows systems or emscripten.
    "zoneinfo": [
        "tzdata>=2024.1 ; sys_platform == 'win32' or sys_platform == 'emscripten'",
        "backports.zoneinfo>=0.2.1 ; python_version<'3.9'",
    # We only support Django versions with upstream support - see
    # We also leave the choice of timezone library to the user, since it
    # might be zoneinfo or pytz depending on version and configuration.
    "django": ["django>=3.2"],

The way this works when installing Hypothesis normally is that these features become available if the relevant library is installed.

Specifically for pytest, our plugin supports versions of pytest which have been out of upstream support for some time. Hypothesis tests can still be executed by even older versions of pytest - you just won’t have the plugin to provide automatic marks, helpful usage warnings, and per-test statistics.

Testing Hypothesis

If you want to test Hypothesis as part of your packaging you will probably not want to use the mechanisms Hypothesis itself uses for running its tests, because it has a lot of logic for installing and testing against different versions of Python.

The tests must be run with fairly recent tooling; check the tree/master/requirements/ directory for details.

The organisation of the tests is described in the hypothesis-python/tests/README.rst.