Install & Compatibility
Where this runs
tested against v9.2.213 · 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
muslpy 3.10–3.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.3s · import 0.624s · 126MB
123MB installed
● package 123MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Solver
✓ import claripy
s = claripy.Solver()
Main entry point for creating and managing constraints.
BVS
✓ import claripy
x = claripy.BVS('x', 32)
✗ x = claripy.BV('x', 32)
claripy.BV was renamed to claripy.BVS (Bit-Vector Symbol) to clarify its purpose.
BVV
✓ import claripy
y = claripy.BVV(10, 32)
Used to create concrete Bit-Vector Values.
This quickstart demonstrates how to initialize a Claripy solver, create symbolic and concrete bit-vectors, add constraints, and then evaluate the possible values for the symbolic variable. It showcases basic operations like `BVS` for symbolic variables, `BVV` for concrete values, `add` for constraints, and `eval`, `max`, `min` for solution retrieval.
import claripy
s = claripy.Solver()
x = claripy.BVS('x', 8) # Create an 8-bit symbolic bit-vector
y = claripy.BVV(65, 8) # Create an 8-bit concrete bit-vector with value 65
# Add constraints
s.add(claripy.ULT(x, 5)) # Unsigned Less Than x < 5
s.add(x != 1)
# Evaluate the symbolic variable
solutions = s.eval(x, 10) # Get up to 10 possible solutions for x
print(f"Possible values for x: {sorted(solutions)}")
assert sorted(solutions) == [0, 2, 3, 4]
# Max and Min values
print(f"Max value for x: {s.max(x)}")
print(f"Min value for x: {s.min(x)}")
Debug
Known issues
breakingThe class `claripy.BV` has been renamed to `claripy.BVS` (Bit-Vector Symbol). Old code using `claripy.BV` will break.fixReplace all instances of `claripy.BV` with `claripy.BVS`.
affects: Likely around Angr 4.6.3.28 release cycle (older versions)
deprecatedAccessing bit-vectors via `state.BV` or `state.BVV` within an Angr state is deprecated.fixUse `state.se.BVS` and `state.se.BVV` instead when working with symbolic expressions attached to an Angr state (`state.se` refers to the symbolic execution engine).
affects: Likely around Angr 4.6.3.28 release cycle (older versions)
deprecatedThe `BV.model` attribute is deprecated.fixInstead of `BV.model`, convert the bit-vector with the appropriate backend directly, e.g., `claripy.backend_concrete.convert(bv)` if you need a specific model.
affects: Likely around Angr 4.6.3.28 release cycle (older versions)
gotchaClaripy has strong dependencies on specific `z3-solver` versions. Incompatibilities can lead to `AttributeError` (e.g., `Z3_get_symbol_string_bytes`) or functional issues, especially with floating-point operations.fixEnsure `z3-solver` is installed at the exact version specified by Claripy's `pyproject.toml` or the Angr project. For current versions, this is `z3-solver==4.13.0.0`.
affects: All versions, especially when upgrading `z3-solver` independently.
Errors
Common errors & fixes
claripy.errors.UnsatError
The set of constraints added to the Claripy solver are contradictory, meaning there are no possible values for the symbolic variables that can satisfy all conditions simultaneously.
fixReview the constraints being added to the solver, especially those involving logical operations (AND, OR) or comparisons, to identify and remove conflicting conditions. Use `solver. satisfiable()` to check for satisfiability before attempting to evaluate, and `solver.unsat_core` if available, to identify the subset of constraints causing unsatisfiability.
ClaripySizeError: bitwidth mismatch
This error occurs when attempting to perform an operation on Claripy BitVector (BV) or BitVectorValue (BVV) objects that have different or incompatible bit widths, and the operation requires them to be of the same size.
fixEnsure that all BitVector objects involved in an operation (e.g., concatenation, arithmetic, comparisons) have compatible bit widths. Use methods like `extend()`, `zero_extend()`, `sign_extend()`, or `Extract()` to adjust bit widths as necessary before performing the operation.
AttributeError: 'int' object has no attribute 'symbolic'
This error arises when a standard Python integer is treated as a Claripy symbolic object, specifically when trying to access attributes or methods (like `symbolic`) that only exist on Claripy AST objects.
fixDistinguish between concrete Python integers and Claripy symbolic BitVector objects. When working with symbolic variables, ensure they are created using `claripy.BVS()` or `claripy.BVV()` and operations are performed using Claripy's methods. Convert concrete values to Claripy BVVs if they need to interact with symbolic expressions, e.g., `claripy.BVV(10, 32)`.
TypeError: 'claripy.ast.Base.Base' object is not callable
This error typically occurs when a Claripy Abstract Syntax Tree (AST) object, particularly a base AST or a specific type like a BitVector, is incorrectly treated as a function and an attempt is made to call it.
fixClaripy AST objects represent expressions, not functions. Instead of calling the AST object directly, use Claripy's solver methods (e.g., `solver.eval()`, `solver.min()`, `solver.max()`) to evaluate the expression to concrete values, or use appropriate AST methods for manipulation (e.g., `.zero_extend()`, `.chop()`). Remember that operations like `a + b` construct new ASTs, they don't 'call' `a` or `b`.
BackendError: Unknown Z3 error in abstraction
This indicates an underlying issue within the Z3 SMT solver backend that Claripy uses. It can be caused by an outdated Z3 version, an unexpected input format passed to Z3, or an internal Z3 bug that Claripy's abstraction layer cannot handle.
fixFirst, ensure your `z3-solver` and `claripy` installations are up-to-date, as this often resolves compatibility issues. If the problem persists, try to isolate the specific Claripy operation or set of constraints that trigger the error to report a more detailed bug to the Claripy/Angr project. Sometimes, simplifying complex expressions or constraints can help Z3 process them more reliably.
Upgrade
Version history
9.3.3latest on PyPI · released Aug 19, 2026
Audit
Dependencies
cachetoolsrequiredUsed for caching mechanisms within the solver engine.
typing-extensionsrequiredProvides backported and future typing features.
z3-solverrequiredPrimary SMT solver backend for symbolic execution. Requires a specific version (e.g., 4.13.0.0) for full compatibility.