Skip to content
This repository


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

file 203 lines (155 sloc) 8.824 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203
Installation instructions for OpenImageIO

For the most up-to-date build instructions (and in any case somewhat
more detailed than here), please see our wiki:

Supported platforms at present include Linux (32 and 64 bit),
Mac OS X, and Windows.

Our build system is based upon 'CMake'. If you don't already have it
installed on your system, you can get it from

After you build OpenImageIO, if you compiled with the EMBEDPLUGINS=0 flag
you will need to set the environment variable OIIO_LIBRARY_PATH to point
to the 'lib' directory where OpenImageIO is installed, or else it will
not be able to find the plugins.

Building OpenImageIO on Linux or OS X

The following dependencies must be installed to build the core of
OpenImageIO: Boost, libjpeg, libtiff and OpenEXR. These can be installed
using the standard package managers on your system. Optionally,
to build the image viewing tools, you will need Qt, OpenGL, and GLEW.

On OS X, these dependencies can be installed using MacPorts or
Homebrew. After installation of either of these package installers,
use the "port" or "brew" commands (respectively) to install the
dependencies (e.g. "port install qt4-mac" or "brew update;
brew doctor; brew install qt") before invoking make as described below.

Dependent libraries can be installed in either the system default
locations or in custom directories. Libraries installed in custom
directories must notify the CMake system using environment variables.
For example, set QTDIR to point at the root of the Qt library location
so that CMake can find it (see CMake configuration output).

On Linux and OS X, you can build from source from the top-level
directory by just typing 'make'. (Yes, we have a 'make' wrapper around
our CMake build, it simplifies things.)

During the make, various temporary files (object files, etc.) will
be put in build/PLATFORM, where 'PLATFORM' will be the name of the
platform you are building for (e.g., linux, linux64, macosx).

The result of the make will be a full binary distribution in

Make targets you should know about:

    make Build an optimized distro in dist/PLATFORM,
                            with temp files created while building in
    make debug Build a debugging (symbols, not stripped) distro,
                            will end up in dist/PLATFORM.debug
    make clean Get rid of all the temporary files in
    make realclean Get rid of both build/PLATFORM and dist/PLATFORM
    make nuke Get rid of all build/ and dist/, for all
    make profile Build a profilable version on dist/PLATFORM.profile
    make doxygen Build the Doxygen docs
    make help Print all the make options

Additionally, a few helpful modifiers alter some build-time options:

  make VERBOSE=1 ... Show all compilation commands
  make EMBEDPLUGINS=0 ... Don't compile the plugins into libOpenImageIO
  make USE_OPENGL=0 ... Skip anything that needs OpenGL
  make USE_QT=0 ... Skip anything that needs Qt
  make MYCC=xx MYCXX=yy ... Use custom compilers
  make FORCE_OPENGL_1=1 ... Force iv to use OpenGL's fixed pipeline
  make USE_TBB=0 ... Don't use TBB
  make USE_PYTHON=1 ... Build the Python binding
  make BUILDSTATIC=1 ... Build static library instead of shared
  make LINKSTATIC=1 ... Link with static external libraries when possible
  make SOVERSION=nn ... Include the specifed major version number in the
                                shared object metadata
  make NAMESPACE=name Wrap everything in another namespace

Building on Windows

See the latest Windows build docs on our web site:

1. Check out the trunk or a branch of your choice. The remainder of
these instructions assume that you checked out the trunk to the
D:\OIIO\trunk directory.

2. Download the package with precompiled external libraries from

Next, unpack it. The directory with downloaded code from the repository
and the directory with unpacked libraries should be siblings. For example,

       \trunk // this is my tree
           \src // directory with src files for OIIO
           \build // directory that is created by cmake
       \external // this is extracted external package

3. Download precompiled Qt4 binaries for Windows from here:

Unpack it (it doesn't matter where). After unpacking, add the path to
the Qt bin directory to the PATH variable. For example, if you unpacked
this package to the D:\qt-win directory, you should add D:\qt-win\bin to
your PATH. It's important to add the Qt bin directory to PATH because
the FindQt4 module uses it to search for qmake applications.

4. Also, just to be safe, add QTDIR to the environment variables. It
should point to directory where you unpacked Qt.

5. Download precompiled BOOST 1.38 libraries from

Install it on your system. Choose two versions: Multithread Debug, DLL
and Multithread, DLL for Your Visual Studio version.

5. Download precompiled BOOST 1.38 libraries from here (unfficial
mirror) or from here (unofficial mirror, registration required). Install
it on Your system. Choose two versions: Multithread Debug, DLL and
Multithread, DLL for Your Visual Studio version.

6. Install cmake. You can download precompiled binaries from here:
After installing, run cmake-gui. Set the field that specifies the source
code location (for example, to D:\OIIO\trunk\src). Then set the field
that specifies where to build binaries to the directory you want to
build project for OIIO (for example, D:\OIIO\trunk\build).

7. Set the THIRD_PARTY_TOOLS_HOME environment variable to the directory
where are stored unpacked external libraries (for example,
D:\OIIO\external\dist\windows). You can add variables by clicking Add
entry button.

8. Hit the Configure button. Cmake should automatically find externals
libraries and prepare the environment for creating the OIIO project. If
the configuration process ends without errors go to next step. If not,
read the instructions from the end of this tutorial.

9. Hit the Generate button. Cmake will build Visual Studio a solution in
the build directory.

10. That's all. You can open the OpenImageIO solution and start developing
OIIO! Potential problems:

It may happen that cmake won't find zlib, png, tiff or jpeg
libraries. If so you have to set CMAKE_PREFIX_PATH to point to the
directory where the missing libraries are stored. For example, if cmake
can't find ZLIB, add to CMAKE_PREFIX_PATH the
D:\OIIO\external\dist\windows\zlib-1.2.3 directory. If it can't find
ZLIB and PNG, add

Also, if cmake won't find GLEW set up GLEW_INCLUDES and GLEW_LIBRARIES
in cmake-gui. Don't add them (they are already added), just set them.

Test Images

We have yet another SVN project just for containing a set of sample
images for testing OpenImageIO. We split test images into a separate
SVN project in order to make the main source code tree smaller and
simpler for people who don't need the test suite.

git clone

Also, there are collections of images for some of the file formats we
support, and make test expects them to also be present. To run full tests,
you will need to download and unpack the test image collections from:

These images should be placed in a sibling directory to the OpenImageIO
repository named oiio-testimages.

You do not need any of these packages in order to build or use
OpenImageIO. But if you are going to contribute to OpenImageIO
development, you probably want them, since it is required for executing
OpenImageIO's test suite (when you run "make test").
Something went wrong with that request. Please try again.