Install Open Babel#

Open Babel runs on Windows, Linux and MacOSX. You can either install a binary package (the easiest option) or compile Open Babel yourself (also easy, but much more geek cred).

Install a binary package#

Windows#

Open Babel is available as a binary installer for Windows, both 64-bit (preferred) or 32-bit (indicated by x86 in the filename). It includes several command-line tools as well as a graphical user interface (GUI). The latest version can be download from GitHub.

Advanced users may be interested in compiling Open Babel themselves (see Compiling Open Babel).

Linux#

Open Babel binary packages are available from many Linux distributions including Ubuntu, OpenSUSE and Fedora.

In general, we recommend using the latest release of Open Babel (currently openbabel-3-1-1). If this is not available for your Linux distribution, you should compile Open Babel yourself.

Compiling Open Babel#

Open Babel is written in C++. Compiling is the process of turning this C++ into instructions that the computer’s processor can understand, machine code.

Although pre-compiled (or “binary”) packages are available for several platforms, there are several reasons you might want to compile Open Babel yourself:

The current release (openbabel-3-1-1) of Open Babel is not available for your platform. We recommend always using the latest release.
You want more control over the features available. For example, perhaps you want the Python bindings but these were not included in your distribution.
You want to use the latest development code.
You want to add a new feature. It is easy to add new formats or operations to Open Babel as it has a plugin architecture (see Adding plugins).
You just want to compile stuff yourself. We understand.

Open Babel can be compiled on Linux, MacOSX, BSDs and other Unixes, and also on Windows (with Cygwin, MinGW or MSVC).

Requirements#

To build Open Babel, you need the following:

The source code for the latest release of Open Babel
A C++ compiler

Open Babel is written in standards-compliant C++. The best-supported compilers are GCC 4 and MSVC++ 2008, but it also compiles with Clang and Intel Compiler 11.
CMake 2.8 or newer

Open Babel uses CMake as its build system. CMake is an open source cross-platform build system from KitWare.

You need to install CMake 2.8 or newer. This is available as a binary package from the KitWare website; alternatively, it may be available through your package manager (on Linux). If necessary, you can also compile it yourself from the source code.

If you want to build the GUI (Graphical User Interface), you need the following in addition:

wxWidgets 2.8 (or newer)

Binary packages may be available through your package manager (wx-common, wx2.8-headers and libwxbase2.8-dev on Ubuntu) or from http://www.wxwidgets.org/downloads/. Otherwise, you could try compiling it yourself from the source code.

The following are optional when compiling Open Babel, but if not available some features will be missing:

libxml2 development headers are required to read/write CML files and other XML formats (the libxml2-dev package in Ubuntu)
zlib development libraries are required to support reading gzipped files (the zlib1g-dev package in Ubuntu)
Eigen version 2 or newer is required if using the language bindings in the release. In addition, if it not present, some API classes (OBAlign, OBConformerSearch) and plugins (the QEq and QTPIE charge models, the --conformer and --align operations) will not be available.

Eigen may be available through your package manager (the libeigen2-dev package in Ubuntu). Alternatively, Eigen is available from http://eigen.tuxfamily.org. It doesn’t need to be compiled or installed. Just unzip it and specify its location when configuring cmake (see below) using -DEIGEN2_INCLUDE_DIR=whereever or -DEIGEN3_INCLUDE_DIR=wherever.
Cairo development libraries are required to support PNG depiction (the libcairo2-dev package in Ubuntu)
If using GCC 3.x to compile (and not GCC 4.x), then the Boost headers are required for certain formats (CML, Chemkin, Chemdraw CDX, MDL RXN and RSMI)

If you want to use Open Babel using one of the supported language bindings, then the following notes may apply:

You need the the Python development libraries to compile the Python bindings (package python-dev in Ubuntu)
You need the the Perl development libraries to compile the Perl bindings (package libperl-dev in Ubuntu)

Basic build procedure#

The basic build procedure is the same for all platforms and will be described first. After this, we will look at variations for particular platforms.

The recommended way to build Open Babel is to use a separate source and build directory; for example, openbabel-2.3.2 and build. The first step is to create these directories:
```
$ tar zxf openbabel-2.3.2.tar.gz   # (this creates openbabel-2.3.2)
$ mkdir build
```
Now you need to run cmake to configure the build. The following will configure the build to use all of the default options:
```
$ cd build
$ cmake ../openbabel-2.3.2
```
If you need to specify an option, use the -D switch to cmake. For example, the following line sets the value of CMAKE_INSTALL_PREFIX and CMAKE_BUILD_TYPE:
```
$ cmake ../openbabel-2.3.2 -DCMAKE_INSTALL_PREFIX=~/Tools -DCMAKE_BUILD_TYPE=DEBUG
```
We will discuss various possible options later.
At this point, it would be a good idea to compile Open Babel:
```
$ make
```
Have a coffee while the magic happens. If you have a multi-processor machine and would prefer an expresso, try a parallel build instead:
```
$ make -j4    # parallel build across 4 processors
```
And finally, as root (or using sudo) you should install it:
```
# make install
```

Local build#

By default, Open Babel is installed in /usr/local/ on a Unix-like system. This requires root access (or sudo). Even if you do have root access, you may not want to overwrite an existing installation or you may want to avoid conflicts with a version of Open Babel installed by your package manager.

The solution to all of these problems is to do a local install into a directory somewhere in your home folder. An additional advantage of a local install is that if you ever want to uninstall it, all you need to do is delete the installation directory; removing the files from a global install is more work.

To configure cmake to install into ~/Tools/openbabel-install, for example, you would do the following:
```
$ cmake ../openbabel-2.3.2 -DCMAKE_INSTALL_PREFIX=~/Tools/openbabel-install
```
Then you can run make and make install without needing root access:
```
$ make && make install
```

Compile the GUI#

The GUI is built using the wxWidgets toolkit. Assuming that you have already installed this (see Requirements above), you just need to configure cmake as follows:

$ cmake ../openbabel-2.3.2 -DBUILD_GUI=ON

When you run make and make install, the GUI will be automatically built and installed alongside the main Open Babel library and tools.

Compile language bindings#

When configuring CMake, include options such as -DPYTHON_BINDINGS=ON -DRUBY_BINDINGS=ON for whichever bindings you wish to build (valid names are PYTHON, CSHARP, PERL, JAVA or RUBY) or -DALL_BINDINGS=ON to build them all. The bindings will then be built and installed along with the rest of Open Babel. You should note any warning messages in the CMake output.
If CMake cannot find Java, you should set the value of the environment variable JAVA_HOME to the directory containing the Java bin and lib directories. For example, if you download the JDK from Sun and run the self-extracting .bin file, it creates a directory jdk1.6.0_21 (or similar); you should set JAVA_HOME to the full path to this directory.
If CMake cannot find the Perl libraries (which happens on Ubuntu 10.10, surprisingly), you need to configure CMake with something like -DPERL_LIBRARY=/usr/lib/libperl.so.5.10 -DPERL_INCLUDE_PATH=/usr/lib/perl/5.10.1/CORE.
If you are compiling the CSharp bindings, you should specify the CSharp compiler to use with something like -DCSHARP_EXECUTABLE=C:\Windows\Microsoft.NET\Framework\v3.5\csc.exe.
When you run make install, all of the bindings will be installed to the same location as the Open Babel libraries (typically /usr/local/lib).
To prepare to use the bindings, add the install directory to the front of the appropriate environment variable: PYTHONPATH for Python, PERL5LIB for Perl, RUBYLIB for Ruby, CLASSPATH for Java, and MONO_PATH for Mono.

For example, for Python:

$ cmake ../openbabel-2.3.2 -DPYTHON_BINDINGS=ON
$ make
# make install
$ export PYTHONPATH=/usr/local/lib:$PYTHONPATH

Cygwin#

The basic build instructions up above work just fine so long as you use the CMake provided by Cygwin rather than a native Windows installation.

If you get an error about undefined reference to '_xmlFreeTextReader', you need to specify the location of the XML libraries with the -DLIBXML2_LIBRARIES option:

$ cmake ../openbabel-2.3.2 -DLIBXML2_LIBRARIES=/usr/lib/libxml2.dll.a

The language bindings don’t seem to work under Cygwin. If you can get them to work, let us know. Also remember that anything that uses Cygwin runs slower than a native build using MinGW or MSVC++, so if speed is an issue you might prefer to compile with MinGW or MSVC++.

MinGW#

Open Babel builds out of the box with MinGW. It’s an awkward system to set up though, so here are some step-by-step instructions…TODO

Windows (MSVC)#

The main Windows build used by Open Babel uses the Microsoft Visual C++ compiler (MSVC).

Set up the following environment variables:
1. Add the CMake bin directory to the PATH.
2. (Optional, see Requirements above) Set EIGEN2_INCLUDE_DIR to the location of the top level Eigen directory (if installed).
3. (Optional, required for GUI) Set WXWIN to the top level directory of wxWidgets (if installed).
Install the Microsoft Visual C++ 2010 (or newer) compiler.

We use the Visual C++ 2010 (10.0) Express Edition (available for free).

Open a command prompt, and change directory to the windows-vc2008 subdirectory. To configure cmake, and generate the VC++ project files, run default_build.bat.
Double-click on windows-vc2008/build/openbabel.sln to start MSVC++. At the top of the window just below the menu bar, choose Release in the drop-down box.
On the left-hand side, right-click on the ALL_BUILD target, and choose Build.

Troubleshooting build problems#

CMake caches some variables from run-to-run. How can I wipe the cache to start from scratch?

Delete CMakeCache.txt in the build directory. This is also a very useful file to look into if you have any problems.

How do I specify the location of the XML libraries?

CMake should find these automatically if they are installed system-wide. If you need to specify them, try using the -DLIBXML2_LIBRARIES=wherever option with CMake to specify the location of the DLL or SO file, and -DLIBXML2_INCLUDE_DIR=wherever to specify the location of the header files.

How do I specify the location of the ZLIB libraries?

CMake should find these automatically if they are installed system-wide. If you need to specify them, try using the -DZLIB_LIBRARY=wherever option with CMake to specify the location of the DLL or SO file, and -DZLIB_INCLUDE_DIR=wherever to specify the location of the header files.

What environment variables affect how Open Babel finds formats, plugins and libraries?

LD_LIBRARY_PATH - Used to find the location of the libopenbabel.so file.: You should set this if you get error messages about not being able to find libopenbabel.so.
BABEL_LIBDIR - Used to find plugins such as the file formats: If obabel -L formats does not list any file formats, then you need to set this environment variable to the directory where the file formats were installed, typically /usr/local/lib/openbabel/.
BABEL_DATADIR - Used to find the location of the data files used for fingerprints, forcefields, etc.: If you get errors about not being able to find some .txt files, then you should set this to the name of the folder containing files such as patterns.txt and MACCS.txt. These are typically installed to /usr/local/share/openbabel.

Advanced build options#

How do I control whether the tests are built?

The CMake option -DENABLE_TESTS=ON or OFF will look after this. To actually run the tests, use make tests.

How do I do a debug build?

-DCMAKE_BUILD_TYPE=Debug does a debug build (gcc -g). To revert to a regular build use -DCMAKE_BUILD_TYPE=Release.

How do I see what commands cmake is using to build?

Run Make as follows:

$ VERBOSE=1 make

How do I build one specific target?

Just specify the target when running Make. The following just builds the Python bindings:

$ make _openbabel

To speed things up, you can ask Make to ignore dependencies:

$ make _openbabel/fast

How do I create the SWIG bindings?

Use the -DRUN_SWIG=ON option with CMake. This requires SWIG 2.0 or newer. If the SWIG executable is not on the PATH, you will need to specify its location with -DSWIG_EXECUTABLE=wherever.

How do I build the Doxygen documentation?

Use the -DBUILD_DOCS=ON option with CMake. If the Doxygen executable is not on the PATH, you will need to specify its location with -DDOXYGEN_EXECUTABLE=wherever.