{"id":8041,"library":"crosshair-tool","title":"CrossHair","description":"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.","status":"active","version":"0.0.102","language":"en","source_language":"en","source_url":"https://github.com/pschanely/CrossHair","tags":["static analysis","symbolic execution","formal verification","contract programming","testing","SMT solver"],"install":[{"cmd":"pip install crosshair-tool","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Used as the underlying SMT solver; built during installation on some platforms, which can extend installation time.","package":"Z3 solver","optional":false},{"reason":"Required for the VS Code extension to integrate CrossHair.","package":"pygls","optional":true}],"imports":[{"note":"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.","symbol":"CLI tool","correct":"crosshair watch my_module.py"}],"quickstart":{"code":"# my_code.py\ndef divide(a: int, b: int) -> float:\n    \"\"\"\n    post: __return__ == a / b\n    \"\"\"\n    return a / b\n\n# Run CrossHair from your terminal:\n# crosshair watch my_code.py","lang":"python","description":"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."},"warnings":[{"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.","message":"CrossHair 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.","severity":"breaking","affected_versions":">=0.0.102"},{"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.","message":"The 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.","severity":"breaking","affected_versions":"Recent versions (exact version not specified but applies to current)"},{"fix":"Update scripts to use `--example_output_format=arg_dictionary` when using the `cover` command.","message":"The `--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.","severity":"deprecated","affected_versions":">=0.0.38"},{"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.","message":"CrossHair 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be patient during installation. Ensure you have the necessary build tools (e.g., C++ compiler) installed for your operating system.","message":"Installation 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"If your function is not expected to handle these special float values, add a precondition like `pre: math.isfinite(x)` to the function's contract. Alternatively, set the environment variable `CROSSHAIR_ONLY_FINITE_FLOATS=1` to disable this behavior.","cause":"As of version 0.0.102, CrossHair proactively tests float arguments with `math.nan`, `math.inf`, and `-math.inf` to find more robust counterexamples.","error":"CrossHair finds counterexamples for `float('nan')` or `float('inf')` where none were expected before."},{"fix":"Use the corrected option name: `crosshair cover --example_output_format=arg_dictionary`.","cause":"The option name for dictionary output was fixed/renamed in version 0.0.38.","error":"The `crosshair cover` command with `--example_output_format=argument_dictionary` doesn't produce a dictionary output or gives a warning."},{"fix":"Adjust your contracts and expectations, recognizing that the caching mechanism will not be active during CrossHair's analysis. Ensure your function's core logic is correct without relying on the cache during formal verification.","cause":"CrossHair intentionally disables `lru_cache` and `cache` decorators during symbolic execution to avoid non-deterministic behavior that can arise from caching in a symbolic context.","error":"CrossHair analysis seems to ignore my function's `lru_cache` or `cache` decorator, leading to unexpected results or performance characteristics."},{"fix":"This is expected behavior. Allow sufficient time for the Z3 solver to compile. Ensure your system has a C++ compiler and related build tools installed, as these are typically required for the compilation.","cause":"During installation, CrossHair often compiles its underlying SMT solver, Z3, from source. This process can be CPU-intensive and time-consuming on various platforms.","error":"Installation of `crosshair-tool` via pip is taking an unusually long time, seemingly stuck."}]}