Basic Build Instructions

So you've decided you want to build Xuggler yourself. Good on you. It's not for the timid though. This page gives detailed instructions. But if you don't want to deal with this, try one of our installers on the downloads page.

Prerequisite Software

You need to have the following software installed:

OS Software
Additional Windows Requirements
Additional Mac Requirements
  • Get the most recent Apple development tools (Xcode 4.1 or later)

  • Make sure that Xcode still has SDKs available at:


    If not, it's likely because Xcode decided to move them. Make a soft link (change to where your Xcode is):

    sudo ln -s /Applications/ /Developer
  • Some OS X users have found that if the number of environment variables is fewer then 40, javac core dumps. A work around for this is to create a number of dummy environment variables before compiling Xuggler:

    for i in {1..40}; do export xuggler$i=foo; done

    Once Xuggler is installed, these dummy environment variables need not persist. Please pardon the voodoo.

  • Some OS X users have found that adding /usr/local/lib to the DYLD_LIBRARY_PATH environment variable causes problems with a number of command line programs. $XUGGLE_HOME/lib/ will need to be added DYLD_LIBRARY_PATH and thus we advise against installing Xuggler directly into /usr/local.

  • We have found that excuting sudo ant install will not get the RED5 environment settings. The following should ensure Xuggler installs into RED5.

    su root
    ant install
  • On Mac, we build the 64 bit version by default (which seems to work with 1.6. It also works with Java 1.5 if you run Java in "-server" mode. If you need to force it to 32 bit (java 1.5 client mode), pass the following option on all ant calls:

Optional Software See the Optional Software Section in the Advanced building topics.

Getting the Source Code

You can get the latest Xuggler source code here:

git clone git://

Setting up your environment

Xuggle looks for an environment variable called XUGGLE_HOME to determine where to install itself to.

You will also need to add $XUGGLE_HOME/bin to the PATH variable on your system, and $XUGGLE_HOME/lib to the dynamic library load directories on your system. The following table summarizes the settings for the major OS groups.

OS Environment settings

You can set XUGGLE_HOME to any directory you like, and if not set, we'll default to /usr/local (like most open source projects). You may want to use your own setting though to make it easier to add and remove, and to avoid overwriting any other installations of FFmpeg you may have.

export XUGGLE_HOME=/usr/local/xuggler
Optionally, set $XUGGLE_REPO to a directory where you want ant to install published ivy jars (if you don't set it, it defaults to dist/ivy in your build directory).
Mac OS-X
export XUGGLE_HOME=/usr/local/xuggler
Optionally, set $XUGGLE_REPO to a directory where you want ant to install published ivy jars (if you don't set it, it defaults to dist/ivy in your build directory).

Building on Windows is a big PITA. Alas, Windows doesn't have a nice command line way of setting variables, but using their GUI tool, set the following:

  • Set XUGGLE_HOME to a directory of your choice (make sure the directory exists on disk). When building, you must make sure that your XUGGLE_HOME is on your C: drive, and is in a path with no spaces in it. Sorry. This restriction does not apply if you use the installer.
  • Add %XUGGLE_HOME%\bin; to the start of your PATH environment variable.
  • Optionally, set %XUGGLE_REPO% to a directory where you want ant to install published ivy jars (if you don't set it, it defaults to dist/ivy in your build directory).

Building (the easy way)

After you've checked out the latest code, run the following from that directory:

ant run-tests

Check that all tests ran 100% successfully. If they did, then execute:

sudo ant install

to install the shared libraries into their default $XUGGLE_HOME location.

Building the 64-bit version of Xuggler

Note: If you're using a 64-bit JVM you must build the 64-bit version of Xuggler

On OS except Mac, the build should auto-detect 64 bit versus 32 bit. On Mac you'll default to 64-bit. If you need 32-bit binaries (for example, for the Apple Java 1.5 JVM in client mode), you'll need to tell the build system to build 32 bit. For that:

ant -Dbuild.configure.os=i386-apple-darwin clobber run-tests

And here for example is building the 64-bit of windows .

ant -Dbuild.configure.os=x86_64-w64-mingw32 clobber run-tests

You must pass the same -D option to every call of ant.

Cleaning Your Build Tree

To clean out your build tree of all Java compiled files, run:

ant clean-java

This will not clean out the native build tree (as that is often time consuming to rebuild). To completely nuke all generated files, including native files, run:

ant clobber

Supported Operating Systems

Here's a list of the OSes we know Xuggle has been built and run on (with all tests passing 100%). You're welcome to try building on other systems, but your mileage may vary. Please let us know your results if you do so we can update this page.

OS Family OS Version 32 Bit 64 Bit
Windows Windows 7 & Vista Yes Builds, but not tested
XP Yes No
Versions 7 & higher.
Yes Yes
Versions 8.04 LTS (Hardy Heron) & higher.
Yes Yes
Mac OS-X 10.5 Yes Yes

Advanced Building Topics

Hopefully the simpler build set-up works for you, but if not, you can delve even further into the mix of Java and Native build systems we use for Xuggler

Read Xuggler Advanced Building Topics »