---
id: icontract
version: "2.7.3"
license: License :: OSI Approved :: MIT License
license_treatment: permissive
maintenance: aging
---

# icontract — Provide design-by-contract with informative violation messages.

License: permissive · Maintenance: aging · Downloads: 408.3K/mo

## What it is and what it does

icontract is a Python library that implements design-by-contract through decorators, allowing you to declare preconditions (what must be true before a function runs), postconditions (what must be true after), and invariants (what must always be true for a class). When a contract is violated, it raises a ViolationError with a detailed message that includes the contract condition itself, the values of all relevant variables at the time of violation, and any custom description you provided.

The library is built on three runtime dependencies: asttokens, contextvars, and typing_extensions. It supports Python 3.6 through 3.13 and has been in production use since 2018. Unlike simpler assertion-based approaches, icontract automatically extracts and displays variable values without requiring you to write custom error messages, following the DRY principle. It also supports contract inheritance, allowing subclasses to weaken preconditions and strengthen postconditions.

Use it for:

- Add runtime validation to library APIs to catch misuse early with informative error messages
- Document and enforce class invariants in complex stateful objects to prevent invalid states
- Verify function inputs and outputs in data processing pipelines to catch logic errors
- Generate automated test cases by inferring test strategies from contracts
- Enforce contracts on HTTP APIs to validate request and response contracts

## Worth the install?

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

icontract enforces design-by-contract in Python through decorators that validate preconditions, postconditions, and class invariants, with detailed violation messages showing source code and variable values.

Yes, if you want runtime contract enforcement with detailed diagnostics. The permissive MIT license, low install friction, and lack of known vulnerabilities make it safe to adopt. Aging maintenance (197 days since last release) is a minor concern but not a blocker—the library is stable and the repository remains active. Best suited for teams that value explicit contract documentation and detailed failure messages over minimal runtime overhead.

## Install

pip install icontract
uv add icontract
poetry add icontract

## Installing icontract

Before you install: Low friction install with three lightweight runtime dependencies (asttokens, contextvars, typing_extensions). Maintenance status is aging—last release was 197 days ago—but the repository remains active and unarchived with 411 stars.

License in practice: MIT license (permissive) places no restrictions on use, modification, or distribution in proprietary or open-source projects.

Quickstart:

pip install icontract

import icontract

@icontract.require(lambda x: x > 3)
def some_func(x: int) -> None:
    pass

some_func(x=5)  # succeeds
some_func(x=1)  # raises ViolationError with details

Verify before relying:

- Performance overhead of contract checking at runtime compared to assertion-based alternatives
- Compatibility with async/await patterns and coroutines
- Whether inheritance contract weakening/strengthening works correctly with multiple inheritance

## Package facts

- License: License :: OSI Approved :: MIT License (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: aging
- Downloads: 408.3K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

design by contract python, precondition postcondition decorator, contract validation enforcement, python code contracts, assertion with detailed messages, invariant checking decorator, runtime contract verification, design-by-contract, runtime-validation, api-documentation

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