crosshair-tool

library0.0.106pypypiunverified

CrossHair is an analysis tool for Python that utilizes symbolic execution to blur the line between traditional testing and type systems. It works by repeatedly calling functions with symbolic inputs and employing an SMT solver to explore execution paths, finding counterexamples to contracts defined within docstrings. The library currently stands at version 0.0.102 and has a fairly active release cadence with frequent minor updates.

testing

pip install crosshair-tool

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CROSSHAIR-TOOL

crosshair-tool

testingpythonv0.0.106

Install

4.0s avg

Import

—

Disk

80MB

Pass rate

5/ 10

Env Coverage5 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.0.106 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

build_error

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 4.0s · import 0.000s · 81MB

80MB installed

● package 80MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CLI tool

✓ crosshair watch my_module.py

CrossHair is primarily used as a command-line interface (CLI) tool, not typically imported directly into Python code for analysis. Analysis is performed on Python files containing contracts.

Install CrossHair and then run it from the command line to watch your code for contract violations. Define post-conditions and other contracts within function docstrings. CrossHair will continuously analyze the specified files and report any counterexamples.

# my_code.py def divide(a: int, b: int) -> float: """ post: __return__ == a / b """ return a / b # Run CrossHair from your terminal: # crosshair watch my_code.py

crosshair --version

Debug

Known issues

breakingCrossHair now tests float arguments with `math.nan`, `math.inf`, and `-math.inf` by default. This change in version 0.0.102 is likely to uncover new counterexamples in existing codebases that previously assumed finite float inputs.

fix

Add `math.isfinite(x)` preconditions to your contracts for float arguments as appropriate, or set the environment variable `CROSSHAIR_ONLY_FINITE_FLOATS=1` to revert to previous behavior temporarily.

affects: >=0.0.102

breakingThe default stopping conditions have been fully re-worked. The `--per_condition_timeout` option is no longer the default. Instead, `--max_uninteresting_iterations=5` is used when no other stopping criteria are specified.

fix

Adjust your command-line arguments to use `--max_uninteresting_iterations` instead of or in conjunction with `timeout` options, as it will adapt analysis time to problem difficulty.

affects: Recent versions (exact version not specified but applies to current)

deprecatedThe `--example_output_format=argument_dictionary` option for the `cover` command has been fixed and renamed to `--example_output_format=arg_dictionary`. The old option will issue a warning and be removed in future releases.

fix

Update scripts to use `--example_output_format=arg_dictionary` when using the `cover` command.

affects: >=0.0.38

gotchaCrossHair automatically disables `functools.lru_cache` and `functools.cache` decorators during analysis to prevent non-deterministic errors. Code relying on these caches for functional correctness might exhibit different behavior under analysis.

fix

Be aware that caching will not be active during CrossHair analysis. Design contracts such that their correctness does not implicitly depend on the side effects or memoization provided by these caches during analysis.

affects: All versions

gotchaInstallation of `crosshair-tool` can take a significant amount of time on some platforms. This is due to the underlying Z3 SMT solver being compiled from source as part of the installation process.

fix

Be patient during installation. Ensure you have the necessary build tools (e.g., C++ compiler) installed for your operating system.

affects: All versions

Upgrade

Version history

0.0.106latest on PyPI · released Jun 2, 2026

Audit

Dependencies

Z3 solverrequiredUsed as the underlying SMT solver; built during installation on some platforms, which can extend installation time.

pyglsoptionalRequired for the VS Code extension to integrate CrossHair.

Agent activity

19 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/pschanely/CrossHair ↗

packagehttps://pypi.org/project/crosshair-tool/ ↗

homepagehttps://crosshair.readthedocs.io ↗