User Tools

Site Tools


How to compile Mixxx for macOS

Compiling Mixxx for Mac OS X is a simple process once you have all dependencies and Qt set up properly. This guide assumes you have basic knowledge about using and compiling with the command line (eg: ./configure, make). If you don’t, there is a basic guide available at

1. Install Xcode development tools

Launch the Terminal application, and type the following command string:

  xcode-select --install

Click Install on the software update popup window that will appear, and wait for the download and installation to finish (about 150 MB). It gets placed in the following directory: /Library/Developer/CommandLineTools/

Note: If Xcode is already installed in your system, then Command Line Tools become installed as well (you can check this by trying to run gcc or make from the terminal). To install the latest available version of Xcode for your Mac OS X release, go to Downloading it requires a free registration at Apple's developer site.

2. Install build dependencies

Method 1 - Install using Homebrew

This is the preferred method of compiling Mixxx on OS X

Homebrew is yet another package manager for OS X. It is growing quickly in popularity. Assuming you have already installed Homebrew and gotten it working:

  • Open the Terminal application and use the following command to install the necessary libraries:
brew install scons pkg-config portaudio libsndfile libogg libvorbis portmidi git taglib libshout protobuf flac libjpeg qt5 chromaprint rubberband fftw vamp-plugin-sdk opusfile lilv

If you will be compiling with Qt4, also run:

brew tap cartr/qt4
brew tap-pin cartr/qt4
brew install [email protected]

OPTIONAL: To enable libmodplug based module tracker support.

    brew install libmodplug

If you get the error No available formula for libmodplug , enter the following:

    brew create

Enter Formula name libmodplug if asked for, then enter:

    brew install libmodplug

OPTIONAL: Mixxx supports using OSX-provided versions of the MP3 and AAC codec. If you don't want to use the OSX versions of these codecs you can build the codecs into Mixxx directly. To do this, you have to install the MP3 and AAC codecs using Homebrew:

    brew install libid3tag libmad mp4v2 faad2

Method 2 - MacPorts

Mixxx relies on several external libraries for various features. Fortunately, you can automatically download and install most of these dependencies through MacPorts. MacPorts is a package management system that simplifies the installation of software on Mac OS X.

  • Start by downloading and installing one of the .dmg disk images for MacPorts:
  • Next, open the Terminal application and use the following command to install the necessary libraries:
    sudo port install scons libid3tag libmad portaudio libsndfile libogg libvorbis mp4v2 portmidi faad2 git taglib libshout2 protobuf-cpp
  • Finally, after that has completed, download and install the Qt SDK package for your platform (qt-mac and qt-mac-debug-libs required, SDK-Installer will not work with standard settings).

If This is Your First Time Using MacPorts

After installing MacPorts, using MacPorts to install the required libraries is a simple process. Using the command sudo port install X, where X is the name of each library you’ll need, MacPorts will automatically download and install the required dependencies. This can be done one at time by entering single entries like sudo port install scons for each library listed above or all at once by entering the entire command given above.

Note that if you attempt to install everything at once and an error occurs in installation of a library, MacPorts will not continue past the library that caused the error. For example, if after entering the full command you receive an error with git, you’ll need to sort out the error and then finish the installation by entering sudo port install git taglib libshout2 to properly install git and then continue with installing taglib and libshout2.

If a library already happens to be installed on your computer, that's a time-saver, and you'll see something similar to this:

 ~/Music/mixxx>sudo port install libmad
 Skipping org.macports.activate (libmad ) since this port is already active
 --->  Cleaning libmad

Otherwise, MacPorts will automatically install the library and you'll see something similar to this:

 ~/Music/mixxx>sudo port install libid3tag
 --->  Fetching libid3tag
 --->  Attempting to fetch libid3tag-0.15.1b.tar.gz from
 --->  Verifying checksum(s) for libid3tag
 --->  Extracting libid3tag
 --->  Configuring libid3tag
 --->  Building libid3tag with target all
 --->  Staging libid3tag into destroot
 --->  Installing libid3tag 0.15.1b_0
 --->  Activating libid3tag 0.15.1b_0
 --->  Cleaning libid3tag

Note that the password asked for is an admin password for your local machine. This is because you are going into super-user mode in order to write the libraries to your hard drive. It's basically a safe operation, but they put it behind a password so the area where the libraries are stored doesn't get touched very often.

If you get a message like this:

 Error: Target org.macports.fetch returned: fetch failed

It probably means that the config file for port hasn't been updated. Perhaps there has been a newer version of the library released. You may be hosed at this point, but if you have an older version of the library already installed on your system, it may still compile and run properly.

Method 3 - Compile by hand

You will need to install the following by hand for the compile process:

  • scons (Download, Install guide) – if you have Macports and have already installed its version of python then “sudo port install scons” is also a reasonable way to get this installed.
  • libid3tag (Download) – `./configure && sudo make install` or “sudo port install libid3tag”
  • libmad (Download) – `./configure && sudo make install` or “sudo port install libmad” . If you run into the following error with libmad in 10.6: version.c:1: error: CPU you selected does not support x86-64 instructions run the following export CFLAGS=“-arch i686” then, configure, make, sudo make install as normal.
  • Portaudio Download – Use the latest “v19” trunk snapshot – `./configure && sudo make install` or “sudo port install portaudio”
  • libsndfile (Download) – `./configure && sudo make install` or “sudo port install libsndfile”
  • libogg, libvorbis (Download) – `./configure && sudo make install` or if you have been using port, :?: this will have already been covered by previous ports.:?:
  • mp4v2 (Download) or “sudo port install mp4v2”
  • portmidi (Download, or “sudo port install portmidi”
  • faad2 (Download) or “sudo port install faad2”
  • QT 5 (Download) – get the Mac binary package.
  • Git (Download) – Get the installer for your version of OS X.
  • HSS1394 – only applicable to 1.9+ – “bzr checkout lp:hss1394” then “scons” then “sudo scons install” but you probably don't need it unless you got a HSS1394 MIDI device like the Stanton SCS 1 series. Get around this by including “hss1394=0” when running scons on mixxx (see below).
  • taglib – (Download) – or “sudo port install taglib”
  • libshout – (Download) – or “sudo port install libshout2”
  • protobuf – or “sudo port install protobuf-cpp”
  • vamp-plugin-sdk (optional if not installed, Mixxx uses an internal version)

3. Get Mixxx

If you want to compile Mixxx, you'll need to download the source code. Either grab the source for the latest release off our downloads page, or checkout the latest Mixxx code from our Git repository. Refer to Using Git for more details.

4. Compile and install

If you used Homebrew, you need to set your compiler paths accordingly. In the below code you should customize HOMEBREW_PATH to the path where your Homebrew folder can be found. Copy and paste the code below into ~/.bash_profile:

# See the note below about the Opus workaround.
export CFLAGS="-I$HOMEBREW_PATH/include -I$HOMEBREW_PATH/include/opus"
export CXXFLAGS="-I$HOMEBREW_PATH/include -I$HOMEBREW_PATH/include/opus"

then run source ~/.bash_profile.

Opus Workaround: The version of libopus included with Homebrew has a bug where opusfile.h includes the file opus_multistream.h. In order for this file to be present on the include path, we need to add $HOMEBREW_PATH/include/opus to the include path. This will hopefully be fixed in future versions of libopusfile.

QTDIR will tell scons where to find your Qt installation. Replace %VERSION% with the folder name, e.g. 5.10.1 . Run

brew list --versions qt

to see what version(s) you have installed.

Change to the newly created mixxx directory, and use scons to compile and install:

cd mixxx
scons stdlib=libc++ hss1394=0 mad=0 faad=0 coreaudio=1 verbose=0 qt5=1
scons bundle

If you are compiling with Qt4, replace qt5=1 with qtdir=/usr/local/Cellar/[email protected]/%VERSION%/. Replace %VERSION% with the folder name, e.g. 4.8.7_5 . Run

brew list --versions [email protected]

to see what version(s) you have installed.

This should generate which you can run by double-clicking on or typing open Generating the .app has some expensive scanning and relinking steps so if you want to avoid this you can skip scons bundle and instead on the first run of Mixxx run it as:

./mixxx --resourcePath res/

So that it records res/ in mixxx.cfg as where to find skins, controller mappings, and other resources instead of dying at startup.

Optional: Use Clang to build

On OS X, GCC is a wrapper around Clang – a compiler based on LLVM. Using Clang has various benefits:

The GCC wrapper around Clang on OS X tries to behave like GCC which loses some of these benefits. To use Clang directly, before running scons:

export CC=clang
export CXX=clang++

You can now use clang-specific SCons options.

  • To enable colorized output, use the color=1 scons flag.
  • To enable Address Sanitizer, use the asan=1 scons flag.

Optional: Alternate source of MP3/M4A support

As of v1.12, Mixxx will use CoreAudio to decode MP3 and AAC files by default. If you want to use libmad or libfaad for MP3 and AAC decoding, simply set the mad and faad flags and clear the coreaudio flag. To enable libmodplug based module tracker support, set the modplug flag. For example:

scons hss1394=0 mad=1 faad=1 coreaudio=0 modplug=1 verbose=0

Common error messages & solutions

ld: symbol(s) not found for architecture x86_64

OSX 10.9 Mavericks has changed the stdlib default to libc++. If you are on OSX 10.9 Mavericks and get this link error, try the “scons” command above like this:

scons stdlib=libc++
Error: QT path does not exist or QT5 is not installed.

If you installed Qt to a custom location you will have to provide this via the qtdir flag. For example, you could try:

scons qtdir=/Developer

Because /Developer is a common place for Qt to drop its frameworks.

Missing "initializer_list".

This most likely means you are building Mixxx with libstdc++ and not libc++. Mixxx versions newer than 2.0 now require C++11 so libstdc++ is no longer an option since it does not support C++11 features like initializer_list.

ld: warning: in /opt/local/lib/libGLU.dylib, file was built for unsupported file format which is not the architecture being linked (i386)

Try the “scons” command above like this:

scons machine=x86_64

5. Create an XCode project (optional)

If you want to work on Mixxx with XCode for an IDE:

This is taken from the Scons site, who have a pretty good description of how to get a scons project up and running in XCode:

  1. File→New Project→Mac OSX →Others, choose “External Build System”
  2. Save the project into the same directory as your SConstruct file.
  3. In Groups and Files → Targets, double click the target that was automatically created.
  4. Fill in the blanks, i.e. the full path to scons - like “/System/Library/Frameworks/Python.framework/Versions/2.3/bin/scons” or “/usr/local/bin/scons”
  5. You should now be able to build using the Build command from Xcode
  6. Right click “Executables” and choose “Add new custom executable” and point it to the executable you are building and then you can debug using Xcode.
    1. Note: In Xcode 4 there is no “Add new custom executable” option—you must instead edit the current scheme in order to choose an executable to run. You can do this by clicking the project name in the upper-left corner of the window and choosing “Edit Scheme…” or by going to Product → Scheme → Edit Scheme. In the edit menu you can also add arguments to be passed to the executable (such as a resource path) when it is launched.
  7. Use Debug → Breakpoints menu to add a symbolic breakpoint at main() - just type main where it says 'Double click for Symbol' - if you don't add this break point none of the breakpoints set in the editors will work, because gdb doesn't have the symbol information until you start debugging (Jim Ingham suggests turning off “Lazy Symbol Loading” in Debug Preferences.)
Translations of this page:
compiling_on_os_x.txt · Last modified: 2018/07/07 10:39 by jus