Setting up the Python API of CPLEX

The Python API of CPLEX is part of IBM ILOG CPLEX Optimization Studio.


The CPLEX Python API is a lightweight wrapper around the C API (CPLEX Callable Library). As such, it provides access to nearly all of the functionality CPLEX has to offer. Variables and constraints are identified by their indices in the matrix. This topic explains how to set up the CPLEX Python API.

DOcplex is an object-oriented modeling Python API that is numpy/pandas friendly. The model can be solved locally (using the CPLEX Python API under the hood), or on the cloud. In addition to providing access to CPLEX for mathematical programming, it can also be used to access the CP Optimizer constraint programming engine. For more information about using the DOcplex Python API with the CPLEX or the CP Optimizer engines, see DOcplex Python Modeling API.

The modules associated with the CPLEX Python API reside in the directory yourCPLEXhome/python/VERSION/PLATFORM, (or in the folder yourCPLEXhome\python\VERSION\PLATFORM) where yourCPLEXhome specifies the location where CPLEX is installed as part of IBM ILOG CPLEX Optimization Studio, VERSION designates a version of Python compatible with CPLEX, and PLATFORM stands for your combination of operating system and compiler.

There are two alternative ways to set up the Python API of CPLEX.
  • The preferred and most common way is to use the script located in the directory yourCPLEXhome/python/VERSION/PLATFORM (or in the folder yourCPLEXhome\python\VERSION\PLATFORM).
  • Alternatively, you can set the environment variable PYTHONPATH to yourCPLEXhome/python/VERSION/PLATFORM and start running Python scripts with CPLEX.
Both of these methods are detailed further in the following paragraphs.

Using the script

To install the CPLEX-Python modules on your system, use the script located in yourCplexhome/python/VERSION/PLATFORM. If you want to install the CPLEX-Python modules in a nondefault location, use the option --home to identify the installation directory. For example, to install the CPLEX-Python modules in the default location, use the following command from the command line:

python install

To install in the directory yourPythonPackageshome/cplex, use the following command from the command line:

python install --home yourPythonPackageshome/cplex

Both of those commands (default and home-specified) invoke the Python package distutils. For other options available with that package, consult the documentation of Python distutils.

Setting the environment variable PYTHONPATH

If you run multiple versions of CPLEX side-by-side, then use this way of declaring the location of CPLEX and its Python API to your Python installation by means of the environment variable PYTHONPATH.

To start using the CPLEX Python API, set the Python path environment variable PYTHONPATH to the value of yourCplexhome/python/VERSION/PLATFORM. Setting this environment variable enables that version of Python to find the CPLEX modules that it needs to run Python commands and scripts that use the CPLEX Python API.

Next steps

After setting up your Python environment by means of one of those alternative methods, you can proceed to the topic Starting the CPLEX Python API.