Installing OR-Tools

This page explains how to install OR-Tools, either from a binary distribution or from source code.

Google created OR-Tools in C++, but you can also use it with Python, C#, or Java. Internally, we run it on Linux, but you can also install it on Windows and Mac OS X.

The sections below will guide you through the OR-Tools installation (either binary or source) on the supported platforms:

The source code for OR-Tools is available on Github.

Installing on Linux or Mac OS X

The following sections explain how to install OR-Tools on Linux or Mac OS X. For each platform, you can either install one of the binary distributions (the simplest method), or compile the OR-Tools source code. We recommend the binary distributions unless you plan on using OR-Tools with third-party solvers or making changes to the source code.

Linux/Mac OS X binary installation

The binary distributions work on 64-bit machines only. They have been tested under Ubuntu 16.04 (64-bit), Mac OS X with Xcode 5.x (64-bit, Mac OS X 10.12 and up).

Note: The restriction to 64-bit machines applies only to binary installations—not to source installations.

Software requirements for a Linux/Mac OS X binary installation
  • Before installing OR-Tools with support for Python, you must install Python setuptools. On Linux, you can do so by opening a command window and entering
    sudo apt-get install python-setuptools
  • Before installing OR-Tools with support for C++, Java, and C#, you must install g++. On Linux, you can do so by entering
    sudo apt-get install g++
  • Before installing a binary distribution on Mac OS X, you must install the Xcode Command Line Tools. To do so, open the Terminal, found in /Applications/Utilities/, and enter
    xcode-select --install
  • To use OR-Tools with C#, you must install Mono version 4.2.0 or later, with 64 bit support. You can download the latest version of Mono from the Mono Download page.
Supported languages

OR-Tools provides support for C++, Python (versions 2.7, 3.5, and 3.6), Java, and C#. There are two separate binary distributions, one for Python and the other for C++, Java and C#. (It's a bit odd having a separate distribution for Python, we know, but installation woes force our hand.)

Note: You must install the software for any languages you plan to use before installing OR-Tools.

To install a binary distribution, follow the instructions in one of the following sections, depending on which language you plan to use:

Binary installation with support for Python

Note: Before installing OR-Tools with support for Python, you must install Python setuptools.

To install the binary distribution with support for Python:

  1. Download one of the following archives from Github:
  2. Unpack the archive.
  3. Open a command window and navigate to the directory where you extracted the archive. Then enter the following command:
    make install

Once the installation has finished, you are ready to start running OR-Tools programs.

Binary installation with support for C++, Java, and C#

Note: Before installing OR-Tools with support for C++, Java, and C#, you must install g++.

To install the OR-Tools binary distribution with support for C++, Java and C#:

  1. Download one of the following archives, based on your platform:
  2. Unpack the archive.

To test the installation, open a command window and navigate to the directory where you unpacked the archive. Then enter the following command:

make all
This runs a selection of examples for OR-Tools. If all the examples run successfully, you are ready to start running OR-Tools programs.

Binary installation with support for FlatZinc

The following distributions are for OR-Tools with support for FlatZinc:

Linux/Mac OS X source installation

The following sections explain how to install OR-Tools from source code on Linux or Mac OS X:

Software requirements for a Linux/Mac OS X source installation

To install Or-Tools from source on Linux or Mac OS X, you must first install CMake version 3. You can download a version for your operating system on the CMake download page.

Additional requirements specific to Linux and Mac OS X are described below.

  • Linux requirements

    On Linux, you need to install the following tools: Git (the version control system in which OR-Tools is developed), zlib-devel, bison, flex, autoconf, libtool, python-setuptools, python-dev, svn, gawk, and other packages they depend on. You can do so by running the following command:

    $ sudo apt-get install git bison flex python-setuptools python-dev autoconf \
    libtool zlib1g-dev texinfo help2man gawk g++ curl texlive subversion
    If your platform uses a package management system other than apt-get, use the appropriate command for your system.

    If you plan to use Python and you installed Python via a package management system, make sure the corresponding "python-dev" package is also installed. This includes the Python header file (Python.h), which is required to build Python C extensions.

  • Mac OS X requirements

    On Mac OS X, install Xcode Command Line Tools, which includes Git. (The full Xcode isn't necessary). To install the tools, open the Terminal, found in /Applications/Utilities/, and enter

    xcode-select --install

To use OR-Tools with C#, you must install Mono version 4.2.0 or later. You can download the latest version of Mono from the Mono Download page.

Downloading the source code

You have a couple of options for the source code to install:

  • The latest release — tar.gz or zip

    The release is a stable version of OR-Tools that has been has been fully tested on all the supported platforms. This is the best option unless you want to try out features that have been added since the most recent date.

  • The source code in the OR-Tools repository on GitHub

    These are the latest versions of the files under development. Note that this code may not be fully tested on all the supported platforms.

Previous releases are available from the binary and source archives.

Building the source code

To build the source code:

  1. Download the source code archive and extract the files, or clone the OR-Tools repository on GitHub.
  2. Open a terminal and navigate to the directory where you extracted the files. Then enter the follow command:
    make third_party
  3. Select one of the options below, corresponding to the languages you want to use with OR-Tools.
    • To install C++ only, enter
      make cc
    • To install C++ and Python, enter
      make python
    • To install C++ and Java, enter
      make java
    • To install C++ and C#, enter
      make csharp
    • To install C++, Python, Java, and C#, enter
      make all
Installing third-party solvers

If you want to use the third-party solver SCIP (Solving Constraint Integer Programming) with OR-Tools, do the following steps:

  1. Download a tar file for the SCIP Optimization Suite 4.0.1 and unpack it.
  2. Open a terminal and navigate to the directory where you extracted the tar file.
    • On Linux, enter
      make GMP=false READLINE=false TPI=tny USRCFLAGS=-fPIC USRCXXFLAGS=-fPIC USRCPPFLAGS=-fPIC
    • On Mac OS X, enter
      make GMP=false READLINE=false TPI=tny
  3. Change to the directory where you extracted the OR-Tools archive, as described in the previous section.
  4. Edit the file Makefile.local by adding the line
    UNIX_SCIP_DIR=<path to sciptopsuite-4.0.1>/scip-4.0.1
  5. Enter the following commands:
    make clean
    make cc

To test the installation, enter the following command to solve an integer programming problem using SCIP:

bin/integer_programming
Running tests

You can check that everything is running correctly by entering:

$ make test 

This runs a selection of examples in C++, Python, Java, and C#. If the examples run successfully, you are all set to start running OR-Tools programs.

Cleaning the installation files

If you need to re-install OR-Tools, the command:

$ make clean_third_party

will clean all downloaded source files, all compiled dependencies, and remove Makefile.local. This can be useful for resetting to a clean state, or if you have added an archive in dependencies/archives.

Installing on Windows

The following sections explain how to install OR-Tools on Windows. You can either install one of the binary distributions (the simplest method), or compile the OR-Tools source code. We recommend the binary distributions unless you plan on using OR-Tools with third-party solvers or making changes to the OR-Tools source code.

Windows binary installation

The binary distributions work on 64-bit machines only. They have been tested on Windows 10 under Microsoft Visual Studio 2015 and 2017 (64-bit).

Note: The restriction to 64-bit machines applies only to binary installations—not to source installations.

Software requirements for a Windows binary installation
  • To install a binary distribution on Windows, you must have Visual Studio 2015 or later installed.
  • Before installing OR-Tools with support for Python, you must install Python setuptools.
Supported languages

OR-Tools provides support for C++, Python (versions 2.7, 3.5, and 3.6), Java, and C#. There are two separate binary distributions, one for Python and the other for C++, Java and C#.

Note: You must install the software for any languages you plan to use before installing OR-Tools.

To install a binary distribution, follow the instructions in one of the following sections, depending on which language you plan to use:

Binary installation with support for Python

Note: Before installing OR-Tools with support for Python, you must install Python setuptools.

To install the binary distribution with support for Python:

  1. Download the Python zip archive and unzip it.
  2. Open a Visual Studio Native Tools Command Prompt and change directory to ortools_examples. Then enter the following command:
    make install

Once the installation has finished, you are ready to start running OR-Tools programs.

Binary installation with support for C++, Java and C#

To install the OR-Tools binary distribution with support for C++, Java and C#:

  1. Download one of the following archives, based on your version of Visual Studio:
  2. Unpack the archive.

To test the installation, open a Visual Studio Native Tools Command Prompt and navigate to the directory where you unpacked the archive. Then enter the following command:

make all

This runs a selection of examples for OR-Tools. If all the examples run successfully, you are ready to start running OR-Tools programs.

Installing OR-Tools with FlatZinc support

The following distributions are for OR-Tools with FlatZinc support:

Windows source installation

The following section explain how to install OR-Tools from source code on Windows:

Software requirements for a Windows source installation

The following software must be installed on your computer before you can install OR-Tools from source on Windows:

  • Visual Studio 2015 or later
  • Git—the version control system in which OR-Tools is developed. You can download Git from https://git-scm.com/.
  • SVN—Any version that provides svn.exe
  • CMake 3—download the official .dmg archive from https://www.cmake.org/download. When installing CMake, select the option for cmake to be accessible from the command line.
Downloading the source code

You have a couple of options for the source code to install:

  • The latest release — tar.gz or zip

    The release is a stable version of OR-Tools that has been has been fully tested on all the supported platforms. This is the best option unless you want to try out features that have been added since the most recent date.

  • The source code in the OR-Tools repository on GitHub

    These are the latest versions of the files under development. Note that this code may not be fully tested on all the supported platforms.

Previous releases are available from the binary and source archives.

Building the source code

To build the source code:

  1. Download the archive for the source code, or clone the OR-Tools repository on GitHub.
  2. Add the tools subdirectory of the installation directory to the Windows PATH environment variable.
  3. Open the Visual Studio Native Tools Command Prompt and navigate to the installation directory.
  4. Enter the following command:
    tools\make third_party
  5. Select one of the options below, corresponding to the languages you want to use with OR-Tools.
    • To install C++ only, enter
      tools\make cc
    • To install C++ and Python, enter
      tools\make python
    • To install C++ and Java, enter
      tools\make java
    • To install C++ and C#, enter
      tools\make csharp
    • To install C++, Python, Java, and C#, enter
      tools\make all
      .
Installing third-party solvers

If you want to use the third-party solver SCIP (Solving Constraint Integer Programming) with OR-Tools, do the following steps:

  1. Download the following files and unpack them:
  2. Open a command window and create a directory as follows:
    md scip-4.0.1
  3. Copy the include directory from the scipoptheaders archive to scip-4.0.1.
  4. Copy the file libscipopt.lib from the SCIP compiled library to scip-4.0.1.
  5. Copy the dll file at the top level of the SCIP compiled library to any directory on the Windows PATH.
  6. Change to the directory where you extracted OR-Tools, as described in the previous section.
  7. Edit the file Makefile.local by adding the line
    WINDOWS_SCIP_DIR=<path to scip-4.0.1>
  8. Enter the following commands:
    tools\make clean
    tools\make cc

To test the installation, enter the following command to solve an integer programming problem using SCIP:

bin\integer_programming
Running tests

You can check that everything is running correctly by entering:

$ tools\make test 

This runs a selection of examples in C++, Python, Java, and C#. If the examples run successfully, you are all set to start running OR-Tools programs.

Cleaning the installation files

If you need to re-install OR-Tools, the command:

$ tools\make clean_third_party

will clean all downloaded source files, all compiled dependencies, and remove Makefile.local. This can be useful for resetting to a clean state, or if you have added an archive in dependencies/archives.

Troubleshooting

The following sections describes some possible solutions in case you encounter problems installing OR-Tools:

General troubleshooting
Could not find suitable distribution for ortools
Here's a sample error message:
  • On Unix: No local packages or download links found for ortools>=SOME_VERSION
    error: Could not find suitable distribution for Requirement.parse('ortools>=SOME_VERSION')
    .
  • On Windows: Could not load file or assembly 'Google.OrTools, Version=SOME_VERSION, Culture=neutral, PublicKeyToken=null'.
This occurs when you try to install a binary distribution, but the installer is unable to build the ortools package for your operating system. In this case, you can still install and run OR-Tools from source files, and even build the python package yourself. You can do so, by following these steps:
Can't open y.tab.[ch] or bison: No such file or directory

Sometimes Bison, a parser generator, will fail to build. Bison is only necessary for FlatZinc, a solver input language used for the MiniZinc constraint modeling language. If you don't have an explicit need for those, comment out the install bison line in makefiles/Makefile.third_party.unix and rebuild.

make install_python_module didn't succeed

If you are on OpenSuse (and possibly Red Hat), make install_python_module will fail. One workaround is described on this page: http://stackoverflow.com/questions/4495120/ combine-user-with-prefix-error-with-setup-py-install.

Cannot download pcre

Here's a sample error message:

svn co svn://vcs.exim.org/pcre/code/trunk -r 1336 dependencies/sources/pcre-1336 svn: E000101: Unable to connect to a repository at URL 'svn://vcs.exim.org/pcre/code/trunk' svn: E000101: Can't connect to host 'vcs.exim.org': Network is unreachable make: [dependencies/sources/pcre-1336/autogen.sh] Error 1

Unfortunately, the pcre servers are flaky. Just retry until it works.

Missing gflags.h

Sample error message:

src\base/commandlineflags.h(17) : fatal error C1083: Cannot open include file: 'gflags/gflags.h': No such file or directory tools\make: [objs/alldiff_cst.obj] Error 2

This means that make third_party didn't succeed, or wasn't run.

Error C2143

You're using Visual Studio 2010 and will need to upgrade to a later version (2013 or afterward).

[dependencies/install/lib/protobuf.jar] Error 1

Sample error message:

The system cannot find the path specified
make: *** [dependencies/install/lib/protobuf.jar] Error 1

You need to set the variable WINDOWS_JDK_DIR with the path to your JDK in Makefile.local.
Remember to set the variables WINDOWS_PYTHON_VERSION and WINDOWS_PYTHON_PATH to use python.

'Python.h' file not found

If this error occurs when you run make all or make python, it means that make was unable to find Python's lib or include directories. To specify where make can find them, use the ADD_PYTHON_INC environment variable like so:

make python ADD_PYTHON_INC="-I/PATH/TO/PYTHON/lib -I/PATH/TO/PYTHON/include/pythonVERSION"

Unrecognized visual studio version
This is a Windows-specific error, and it means that the VisualStudioVersion variable is not set in your terminal. If you're using a generic Windows terminal, then opt for a Visual studio one instead of it. If you're already using the latter, then set the VisualStudioVersion to the version of your Visual Studio. For instance, run the following command:
  • set VisualStudioVersion=14.0 for VS2015.
  • set VisualStudioVersion=12.0 for VS2013.
Troubleshooting an installation with Python support
Permission denied: '/Library/Python/.../EGG-INFO/namespace_packages.txt

If you see this error when trying to run one of the Python examples after having followed the instructions above, you probably installed with sudo python setup.py install instead of python setup.py install --user. You can run the examples with sudo, e.g., sudo python examples/golomb8.py.

ImportError: No module named pywraplp

Most likely, you're using Windows XP. Unfortunately, OR-Tools requires Visual Studio 2013 or higher, which is incompatible with Windows XP.

Another common error is using pip, which pulls the wrong archive with a wrong platform. Use easy_install, or better yet, the installation instructions in the OR-Tools Python distribution.

ImportError: Cannot import name

Most likely, you don't have the right versions of the ortools or protobuf modules. To check whether this is the case, run the following command:

make check

If this returns a message saying that your versions of Python or the protobuf modules are different from required versions (or that they are not installed), you need to reinstall OR-Tools as follows:

make install
Other errors

If you see errors when installing the Python build of OR-Tools, you can try upgrading setuptools using the instructions found here.

If you still have problems, especially on Mac OS X, here is a workaround found by a user:

  • Upgrade setuptools from 12.05 to 12.1 by running
    curl https://bootstrap.pypa.io/ez_setup.py -o - | python
  • Run
    pip install ez_setup
  • Install OR-Tools by running
    pip install ortools

Send feedback about...

Optimization
Optimization