Install & Compatibility
Where this runs
tested against v0.11.1 · 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 8.0s · import 0.000s · 226MB
230MB installed
● package 230MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
clarabel
✓ import clarabel
numpy
✓ import numpy as np
sparse
✓ from scipy import sparse
DefaultSolver
✓ clarabel.DefaultSolver
✗ from clarabel import DefaultSolver
Classes like DefaultSolver, DefaultSettings, and cone types are typically accessed via the top-level 'clarabel' module after `import clarabel`.
__version__
✓ clarabel.__version__
✗ clarabel.__version__()
Prior to version 0.11.0, `__version__` was a callable method. It is now a direct attribute.
This quickstart demonstrates how to define and solve a simple quadratic program (QP) using Clarabel. It shows how to define the objective function matrix (P) and vector (q), constraint matrix (A) and vector (b), and the cone structure (K). The problem data is expected in `numpy` arrays and `scipy.sparse.csc_matrix` format.
import clarabel
import numpy as np
from scipy import sparse
# Define problem data for a simple QP: minimize 0.5 * x.T * P * x + q.T * x
# subject to A * x + s = b, s in K
P = sparse.csc_matrix([[3., 1., -1.], [1., 4., 2.], [-1., 2., 5.]])
P = sparse.triu(P).tocsc() # Clarabel expects upper triangular part in CSC format
q = np.array([1., 2., -3.])
A = sparse.csc_matrix([
[1., 1., -1.], # Equality constraint (ZeroConeT)
[0., 1., 0.], # Inequality constraint (NonnegativeConeT)
[0., 0., 1.], # Inequality constraint (NonnegativeConeT)
[0., 0., 0.] # Placeholder for SOC (SecondOrderConeT)
])
b = np.array([1., 2., 2., 0.])
# Define cone constraints: ZeroConeT(dim), NonnegativeConeT(dim), SecondOrderConeT(dim)
cones = [clarabel.ZeroConeT(1), clarabel.NonnegativeConeT(2), clarabel.SecondOrderConeT(1)]
# Instantiate and solve the solver
settings = clarabel.DefaultSettings()
settings.verbose = False # Disable verbose output
solver = clarabel.DefaultSolver(P, q, A, b, cones, settings)
solver.solve()
# Print results
print(f"Solution x: {solver.solution.x}")
print(f"Objective value: {solver.solution.obj_val}")
print(f"Solver status: {solver.solution.status}")
Debug
Known issues
gotchaClarabel's default solver settings are optimized for 64-bit float data. Using 32-bit floats (e.g., `np.float32`) may lead to suboptimal performance or numerical inaccuracies unless solver tolerances are explicitly relaxed.fixEnsure problem data (P, q, A, b) is provided in 64-bit float format (`np.float64`). If 32-bit precision is required, adjust solver settings like `settings.tol_gap_abs` and `settings.tol_gap_rel` accordingly.
affects: All versions
gotchaWhen updating problem data (e.g., in iterative algorithms), modifications to the `cones` array are not permitted. Additionally, data updates are disallowed if `settings.chordal_decomposition_enable = True` or `settings.presolve_enable = True`.fixIf the cone structure or presolve/chordal decomposition settings need to change, a new solver instance must be created. For allowed data updates, ensure the sparsity pattern and problem dimensions remain constant.
affects: All versions
gotchaClarabel expects sparse matrix data (P and A) to be in Compressed Sparse Column (CSC) format, as produced by `scipy.sparse`. For the quadratic objective matrix `P`, only its upper triangular part should be provided in CSC format.fixAlways convert sparse matrices to `scipy.sparse.csc_matrix`. For the 'P' matrix, use `P = sparse.triu(P).tocsc()` to ensure correct format and content.
affects: All versions
breakingFrom Clarabel version 0.11.0 onwards, the version string is accessed via `clarabel.__version__` (an attribute) instead of `clarabel.__version__()` (a method).fixUpdate any code that retrieves the Clarabel version from `clarabel.__version__()` to `clarabel.__version__`.
affects: >=0.11.0
deprecatedStarting with CVXPY 1.5, Clarabel has become the default interior-point solver, replacing ECOS. CVXPY 1.6 will entirely remove ECOS as a dependency. Users relying on ECOS's specific behavior via CVXPY might experience regressions.fixIf experiencing issues with Clarabel as the default in CVXPY, explicitly specify a different solver (e.g., `problem.solve(solver='ECOS')` if ECOS is installed, or `solver='SCS'`). Consider installing ECOS manually if needed with CVXPY >=1.6.
affects: CVXPY >=1.5 (indirectly affects Clarabel users)
Errors
Common errors & fixes
Clarabel NUMERICAL_ERROR
The solver terminated prematurely due to numerical instability during the optimization process, often caused by ill-conditioned problem data or extreme values.
fixCheck the scaling of your problem data (P, q, A, b) to ensure values are not excessively large or small. Consider adjusting solver settings like `equilibrate_enable` or `max_iter` to improve robustness, or verify the problem formulation itself for potential numerical issues.
Clarabel INSUFFICIENT_PROGRESS
The solver halted because it could not make sufficient progress towards a solution within the given tolerances or iteration limits, which can occur with poorly conditioned problems, highly constrained problems, or non-convergence.
fixInspect the problem data for poor scaling. Adjust solver parameters such as `max_iter`, `tol_primal_feas`, `tol_dual_feas`, or `tol_gap_abs` to relax convergence criteria, or ensure the problem is well-posed and feasible. If using CVXPY, this status might be mapped to a `SolverError` and specific handling might be needed.
Clarabel PRIMAL_INFEASIBLE
The optimization problem is primal infeasible, meaning no solution exists that satisfies all primal constraints. This indicates an issue with the problem formulation itself.
fixCarefully review your constraints (A, b, and cone definitions) to ensure they are logically consistent and that a feasible region exists. This may involve relaxing some constraints or re-evaluating the problem's physical or mathematical basis.
Upgrade
Version history
0.11.1latest on PyPI · released Jun 11, 2025
Audit
Dependencies
pythonrequiredRequired Python version.
numpyrequiredCommonly used for numerical array operations with problem data.
scipyrequiredRequired for sparse matrix (CSC format) representation of problem data.
cvxpyoptionalOptional: Can be used as an interface for modeling problems to be solved by Clarabel.