Source installation (OS X, Ubuntu)

Optional: Setting up the MATLAB Compiler

Make sure that the MATLAB executable is in your path. (e.g., typing matlab at the system command line should start an instance of MATLAB). For example, on Mac you might consider sudo ln -s /Applications/ /usr/bin/matlab, or you can actually add the MATLAB/bin directory to your system path.

Getting Drake

We recommend that you setup SSH access to to avoid needing to type your password each time you access it. The following instructions assume you have uploaded your public SSH key to your Github account.

Now run:

git clone drake-distro

Note: the build process may encounter problems if you have unusual characters like parentheses in the absolute path to the drake-distro directory (see #394).

The above git clone command will configure Drake’s primary repository as a remote called origin. We recommend that you configure your fork of Drake’s primary repository as the origin remote and Drake’s primary repository as the upstream remote. This can be done by executing the following commands:

cd drake-distro
git remote set-url origin[your github user name]/drake.git
git remote add upstream
git remote set-url --push upstream no_push

Mandatory platform specific instructions

Before running the build, you must follow some one-time platform-specific setup steps:

See supported configurations for the configurations and platforms that Drake officially supports. All else being equal, we would recommend developers use Ubuntu Xenial.

Build the collection

There are three ways to build Drake:

  1. Using Make
  2. Using Ninja
  3. Using ROS Catkin

For instructions on how to switch build systems, see this subsection.

Make support is more mature, but Ninja is faster, more modern, and will receive more investment from the Drake development team going forward.

Build with Make

First, confirm that Make is installed on your system by executing:

make --version

To build with Make, execute:

cd drake-distro
mkdir build
cd build
cmake ..

Do NOT use sudo. Just make is sufficient, and will prevent problems later. Feel free to use make -j if your platform supports it. Note that the above cmake command does not specify a build type, so drake will be built with Release by default. If you wish to build with a different build type, change the cmake command to cmake .. -DCMAKE_BUILD_TYPE:STRING=Debug to build with build type “Debug”. Alternative build modes include “RelWithDebInfo” and “Release”. They differ in terms of the amount of debug symbols included in the resulting binaries and how efficiently the code executes.

In addition to the build mode, Drake has many other build options. You can view them in drake-distro/CMakeLists.txt. The build options typically start with “WITH_”. The options can be included in the above cmake command by adding additional -D flags. You can also specify them using a text-based GUI by executing:

cd drake-distro/build
ccmake ..

To get details about the actual compiler and linker commands, execute:

cd drake-distro/build
make VERBOSE=true

Build with Ninja

First, confirm that Ninja is installed on your system:

ninja --version

Drake uses CMake to generate Ninja files within an out-of-source build directory. You can configure CMake options by passing them at the cmake command line with -D, or in a GUI by running ccmake instead of cmake. For instance, the following sequence of commands generates Ninja files, and then runs the Ninja build.

cd drake-distro
mkdir build
cd build
cmake .. -G Ninja

Ninja can rebuild Drake from within drake-distro/build/drake/ without rebuilding the entire super-build. It can also build specific targets. Tab-completion is supported.

cd drake-distro/build/drake

To review the raw shell commands, compiler flags, and linker flags that CMake generated, consult and drake/, or run ninja -v for a verbose build.

Build with ROS Catkin


Locations of Build and Install Directories

This section contains information about where Drake’s build artifacts are located. They assume you are following the official from-source build instructions given above. The locations will differ if you’re building Drake using an alternative method, e.g., completely out of source.

Builds based on Make and Ninja place build artifacts in drake-distro/build/. Externally visible build artifacts are placed in drake-distro/build/install.

Builds using ROS Catkin place build artifacts in Catkin’s development space and place externally-visible build artifacts in Catkin’s install space. When following the official Drake/ROS installation instructions, these spaces are typically drake_catkin_workspace/devel and drake_catkin_workspace/install, respectively.

Identifying the Build System Used

If you encounter an existing from-source installation of Drake and aren’t sure whether it was built using Make or Ninja, [1] look in drake-distro/build. If there is a file called Makefile, Drake was built using Make. If there is a file called, Drake was built using Ninja.

[1]ROS Catkin is not listed since you should immediately know if Drake was compiled using ROS Catkin based on whether it is located in a ROS workspace. Once compiled using Catkin, do not attempt to switch build systems.

How to Switch Build Systems

To switch between using make vs. ninja, first clean your workspace. Then follow the original build instructions using the desired build system.

How to Clean Your Workspace

First save, commit, and push all of your work. The following commands are destructive.

If you’re using make or ninja, execute:

cd drake-distro
rm -rf build
rm -rf externals
git clean -fdx
git reset --hard HEAD

If you’re using ROS Catkin, simply execute:

cd drake_catkin_workspace
catkin clean

Test Your Installation

Start MATLAB, then at the MATLAB prompt do:

cd drake-distro/drake

Then cd into the examples directories and try some things out. Here are a few fun ones to get you started:

  • runLQR in the examples/CartPole directory
  • runLQR in the examples/Quadrotor2D directory
  • in the examples/RimlessWheel directory
  • in the examples/PlanarMonopodHopper directory

To run some unit tests, execute the following:

cd drake-distro/build/drake
ctest -VV

For more details on how to run Drake’s unit tests, see the instructions here: Detailed Notes on Drake’s Unit Tests.

If you have problems, please check the Frequently Asked Questions. If the solution is not there, or if you discover something missing from our installation instructions or lists of prerequisites, then please file an issue and label it as installation.

Using SNOPT as an external

Drake includes support for SNOPT, but is not able to redistribute it directly. To use SNOPT with Drake, you must have access to its private GitHub repository, and you must set up a GitHub SSH key on your machine. Follow the instructions in the GitHub documentation.

This capability is meant for members of MIT Robot Locomotion Group and close collaborators with whom RLG shares licenses.

Using Gurobi as an external

Before building Drake with Gurobi, create an account and obtain a license on Gurobi’s website. Download Gurobi 6.0.5, and set the GUROBI_DISTRO environment variable to the absolute path to the downloaded file. Consult Gurobi’s documentation to activate your license; exact procedures depend on license type. Once activated, place your Gurobi license file gurobi.lic in your home directory.

Then enable the CMake option WITH_GUROBI in the Drake superbuild, and proceed to build Drake as usual.

Stay up to date

To work on the bleeding edge, do:

cd drake-distro
git checkout master
git pull upstream master
cd build

This is especially useful if you are ready to contribute your work back to the main repository with a pull request.

Bazel support

Drake is adding support for the Bazel build system.


If you’re unable to launch drake-visualizer due to a “No module named vtkCommonCorePython” error, see this FAQ.