Checking out and building OIIO

Windows -- Readme

Windows users have a special page on Building OIIO on Windows.

Checking out the code

OpenImageIO is maintained in Git, on GitHub:

Main project: development trunk

You can clone a read-only copy our git repository:   git clone git:// oiio

Or you can get yourself a GitHub account and fork OIIO's git repository

Or if you just want to get the code and build it, you can download the latest development snapshot as a tarball or zip file.

Release Branches

If you are using OpenImageIO for mission-critical uses, you probably want to be insulated from the day-to-day changes of the development trunk. There are a variety of other stable branches available, and you can see them with this command:

If you are are cloning our repository or forking on GitHub, be aware of the following branch names:

  • master -- the main line development trunk
  • RB-x.y -- the "head" of release branches (e.g., RB-1.6)
  • release -- the current recommended stable release (the last tagged stable point of the current release branch)

Release branches are well tested and very stable -- we only modify them to add critical bug fixes and never break backwards-compatibility of the APIs within a release branch. (In contrast to the "master" branch, aka trunk, which often has new features added, bugs unintentionally introduced, and may sometimes change APIs in a non-back-compatible way.)

External dependencies

We have a number of dependencies (some required, some optional).  In general, the optional ones will be noticed at build time not to be present, and the build will exclude just the parts of OIIO that require them (such as support for a particular image file format that requires a specific library). Packages that OIIO wants include Boost, GLEW, IlmBase and OpenEXR, IJG's libjpeg, libpng, libtiff, zlib, and Qt. You should just use your usual system package installer to get all the dependent packages installed in the usual places on your system.

It's also possible to have dependent packages installed in some nonstandard location, which you may indicate by setting the environment variable THIRD_PARTY_TOOLS_HOME to the directory of the external tools.

Building OpenImageIO

Platforms supported

We know that OpenImageIO builds correctly on:

  • Linux 32 bit
  • Linux 64 bit (tested on Ubuntu 9.10, 10.04, RHEL4, CentOS, Fedora)
  • Mac OS X (10.5 and higher)
  • Windows (see Building OpenImageIO on Windows).
  • FreeBSD


1. Check out a development branch of OpenImageIO, as explained above.

2. Install required dependencies, Boost, libtiff and OpenEXR using your favorite package manager or installers (apt for Ubuntu, MacPorts or Homebrew for OSX).

3. (Optional) Install dependencies required to build the image viewer, iv: Qt, OpenGL and GLEW.  For example, on OSX "port install qt4-mac" for MacPorts or "brew update; brew doctor; brew install qt" for Homebrew.

4. For any dependencies installed in non-standard locations, create appropriate environment variables to inform CMake (e.g. QTDIR).

5. If you're on one of the platforms we are already supporting, you should be able to do a build like this:

cd oiio
Assuming the build succeeds, you will find a complete OpenImageIO distribution tree in oiio/dist/ARCH, where ARCH is the code for the build platform (linux, linux64, macosx, or windows). Underneath this dist area, you will of course find binlibinclude, anddoc subdirectories.

Currently, we don't have a formal "install" command -- you'll have to copy this dist area (or its contents) wherever you want them to go. To successfully use the resulting build, users should ensure that the bin directory is part of their execution $PATH, the lib directory is in their LD_LIBRARY_PATH (or DYLD_LIBRARY_PATH, on OS X), and that the environment variable IMAGEIO_LIBRARY_PATH also points to the libsubdirectory.

We have a Build Troubleshooting page to check if you run into trouble.

Build modes and options

There are a few make commands and targets you should know about:
make help
Print all the make targets and modifiers.
Build OpenImageIO in optimized mode, storing the results in dist/ARCH. Temporary files (object files, etc.) will be stored inbuild/ARCH.
make debug
Build OpenImageIO in debug mode, storing the results in dist/ARCH.debug. Temporary files (object files, etc.) will be stored inbuild/ARCH.debug. This is equivalent to "make DEBUG=1".
make clean
Delete the temporary files in build/ARCH, but leave the fully-built libraries and binaries in dist/ARCH. To similarly clear the debug version, try "make DEBUG=1 clean".
make realclean
Delete both build/ARCH and dist/ARCH. To similarly clear the debug version, try "make DEBUG=1 clean".
make nuke
Delete dist and build areas for all architectures and build modes (equivalent to "rm -rf build dist").
make test
Run the OpenImageIO test suite (requires ../oiio-images to be installed -- see the following section).
make VERBOSE=1
Do a verbose build (with optional targets) showing the exact compile and link commands. This can be useful for debugging the makefiles themselves.
Builds only the part of OpenImageIO that doesn't need OpenGL (i.e., builds everything but iv). Use this if you don't have OpenGL but want to build everything but the viewer. This is also handy if you lack Qt, because iv is also the only part of OpenImageIO that needs Qt.

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 git project in order to make the main source code tree smaller and simpler for people who don't need the test suite.  The images should be installed into a sibling directory to the oiio repository called oiio-testimages.

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 into oiio-testimages from:

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").