CPLEX Python API (Community Edition)

22.1.2.1 verified Fri May 01 auth: no python

Python interface to the IBM ILOG CPLEX optimization engine (Community Edition). Provides access to CPLEX's LP, QP, QCP, and MILP solvers via the C Callable Library. Current version is 22.1.2.1, supporting Python >=3.9. Released approximately yearly.

pip install cplex

Common errors

error CplexError: CPLEX Error 1001: Out of memory. ↓

cause Model too large for Community Edition (1000x1000 limit) or system memory exhausted.

fix

Reduce model size (Community cap) or use licensed CPLEX; if memory, simplify model or increase swap.

error ModuleNotFoundError: No module named 'cplex' ↓

cause cplex package not installed or installed in wrong Python environment.

fix

Run pip install cplex in the current environment (e.g., conda, virtualenv).

error ImportError: libcplex2212.so: cannot open shared object file: No such file or directory ↓

cause CPLEX dynamic library not in library path (Linux) – typically due to missing CPLEX installation from IBM.

fix

Install CPLEX from IBM site (requires installer) or use pip version (includes binaries for common platforms). For pip version, ensure environment variable LD_LIBRARY_PATH includes site-packages/cplex.

error CplexSolverError: CPLEX Error 1217: No solution exists. ↓

cause Problem is infeasible or unbounded.

fix

Check constraints and bounds; use problem.feasopt() to diagnose infeasibility.

Warnings

breaking CPLEX 22.1 dropped Python 3.6/3.7 support. Requires Python >=3.9. ↓

fix Upgrade Python to 3.9+ or downgrade CPLEX to 20.1 (which supports Python 3.6-3.8).

gotcha CPLEX Community Edition limits model size to 1000 variables and 1000 constraints. Attempting larger models raises CplexError. ↓

fix Use the full (non-community) licensed version for larger models.

gotcha Concurrent use of multiple Cplex instances is not thread-safe. Avoid creating Cplex objects in multiple threads without synchronization. ↓

fix Use multiprocessing (processes) instead of threading for parallel solves.

deprecated CPLEX 12.10 deprecated `cplex.callbacks` in favor of the CPLEX Callback API (C-type callbacks). Python interface updated accordingly. ↓

fix Use `problem.register_callback()` with the new callback classes (e.g., `cplex.callbacks.IncumbentCallback`).

Imports

Cplex
wrong
```
import cplex (then using cplex.Cplex())
```
correct
```
from cplex import Cplex
```
Using `import cplex` then `cplex.Cplex()` also works but is less common.

Quickstart

Solves a simple LP: minimize x + 2y subject to x + y = 1, x,y >= 0.

import cplex
from cplex.exceptions import CplexError

prob = cplex.Cplex()
prob.set_problem_name("example")
prob.objective.set_sense(prob.objective.sense.minimize)

# Add variables
names = ["x", "y"]
obj = [1.0, 2.0]
lb = [0.0, 0.0]
ub = [cplex.infinity, cplex.infinity]
prob.variables.add(obj=obj, lb=lb, ub=ub, names=names)

# Add constraint: x + y == 1
prob.linear_constraints.add(
    lin_expr=[cplex.SparsePair(ind=["x", "y"], val=[1.0, 1.0])],
    senses=["E"],
    rhs=[1.0]
)

prob.solve()
print("Solution status:", prob.solution.get_status())
print("x =", prob.solution.get_values("x"))
print("y =", prob.solution.get_values("y"))