Installation

Set up your development environment for building iPlug2 audio plugins

iPlug2 supports cross-platform audio plugin development for macOS, Windows, iOS, visionOS, and Web. Follow the instructions for your target platform(s) below.

System Requirements

macOS

• macOS 10.15 or later
• Xcode 12.0 or later
• 4GB RAM minimum
• 10GB disk space

Windows

• Windows 10 or later
• Visual Studio 2019/2022
• 8GB RAM minimum
• 15GB disk space

iOS/visionOS

• macOS 13.0 or later
• Xcode 15.0 or later
• iOS 15+ or visionOS 26+
• Apple Developer account

macOS Installation

1. Install Xcode

   Download and install Xcode from the Mac App Store or Apple Developer.

   # Install Xcode Command Line Tools
   xcode-select --install
   

   Xcode Command Line Tools are required even if you plan to use CMake exclusively.

2. Install CMake and Ninja

   Install CMake and Ninja using Homebrew:

   # Install Homebrew if not already installed
   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   
   # Install CMake and Ninja
   brew install cmake ninja
   

   Verify the installation:

   cmake --version  # Should be 3.14 or later
   ninja --version
   
3. Clone iPlug2

   Clone the iPlug2 repository:

   git clone https://github.com/iPlug2/iPlug2.git
   cd iPlug2
   
4. Download Plugin SDKs

   Download the free, publicly available SDKs:

   cd Dependencies/IPlug
   ./download-iplug-sdks.sh
   cd ../..
   

   This downloads:

   • VST3 SDK from Steinberg
   • CLAP SDK from the CLAP project
   • WAM SDK for Web Audio Modules

   AUv2 and AUv3 (Audio Units) require no additional SDKs on macOS.

5. Optional: Download Skia Graphics Backend

   If you plan to use the Skia graphics backend (instead of the default NanoVG), download prebuilt Skia libraries:

   cd Dependencies
   ./download-prebuilt-libs.sh
   cd ..
   

   For iOS development:

   cd Dependencies
   ./download-prebuilt-libs.sh ios
   cd ..
   

   NanoVG is the default and requires no additional downloads. It’s faster and lighter than Skia but has fewer features.

6. Verify Installation

   Build and run the IPlugEffect example:

   cd Examples/IPlugEffect
   mkdir build && cd build
   cmake -G Ninja -DCMAKE_BUILD_TYPE=Release ..
   ninja
   

   The plugin should build successfully and be deployed to ~/Library/Audio/Plug-Ins/VST3/.

   Test the plugin by opening it in a DAW like REAPER, Logic Pro, or Ableton Live.

macOS AAX SDK Setup (Pro Tools)

AAX plugins require the AAX SDK from Avid, which must be downloaded manually.

1. Get an Avid Developer Account

   Sign up for a free developer account at Avid Developer.

2. Download AAX SDK

   Download AAX_SDK_2p3p2.zip (or later) from the Avid Developer portal.

3. Extract to Dependencies

   Extract the SDK to iPlug2/Dependencies/IPlug/AAX_SDK/:

   cd iPlug2/Dependencies/IPlug
   unzip ~/Downloads/AAX_SDK_2p3p2.zip
   mv AAX_SDK_2p3p2 AAX_SDK
   
4. Configure SDK Settings

   Modify the AAX SDK settings for compatibility:

   1. Open AAX_SDK/ExamplePlugIns/Common/Mac/CommonDebugSettings.xcconfig
   2. Set the following:

   GCC_VERSION = com.apple.compilers.llvm.clang
   SDKROOT = macosx
   MACOSX_DEPLOYMENT_TARGET = 10.15
   ARCHS = x86_64 arm64
   

   3. Repeat for CommonReleaseSettings.xcconfig

Windows Installation

1. Install Visual Studio

   Download and install Visual Studio 2019 or 2022 (Community Edition is free):

   Download Visual Studio

   During installation, select the “Desktop development with C++” workload.

   Ensure you install the C++ build tools. The default Visual Studio installation may not include them.

2. Install CMake

   CMake can be installed via:

   Visual Studio Installer

   CMake is included with Visual Studio. Enable it in:

   Visual Studio Installer → Modify → Individual Components → CMake tools for Windows

   Standalone Installer

   Download from cmake.org and add to PATH.

   winget

   winget install Kitware.CMake
   

   Verify the installation:

   cmake --version  # Should be 3.14 or later
   
3. Install Ninja (Optional)

   Ninja is a fast build system alternative to MSBuild:

   winget

   winget install Ninja-build.Ninja
   

   Manual Download

   1. Download from ninja-build.org
   2. Extract ninja.exe to a folder
   3. Add folder to system PATH

   Ninja is optional but recommended for faster builds. You can use Visual Studio’s MSBuild instead.

4. Install Git

   Download and install Git from git-scm.com.

   Or use winget:

   winget install Git.Git
   
5. Clone iPlug2

   Open Git Bash or Command Prompt and clone the repository:

   git clone https://github.com/iPlug2/iPlug2.git
   cd iPlug2
   
6. Download Plugin SDKs

   Run the SDK download script in Git Bash:

   cd Dependencies/IPlug
   ./download-iplug-sdks.sh
   cd ../..
   

   Or manually download each SDK:

   • VST3: Steinberg VST3 SDK
   • CLAP: CLAP SDK
   • WAM: Web Audio Modules

   Extract each to Dependencies/IPlug/[SDK_NAME]/

7. Optional: Download Skia Graphics Backend

   If using the Skia backend:

   cd Dependencies
   ./download-prebuilt-libs.sh win
   cd ..
   
8. Verify Installation

   Build the IPlugEffect example:

   Using Ninja

   cd Examples/IPlugEffect
   mkdir build && cd build
   cmake -G Ninja -DCMAKE_BUILD_TYPE=Release ..
   ninja
   

   Using Visual Studio

   cd Examples/IPlugEffect
   mkdir build && cd build
   cmake -G "Visual Studio 17 2022" -A x64 ..
   cmake --build . --config Release
   

   The plugin should build and deploy to %LOCALAPPDATA%\Programs\Common\VST3\

Windows AAX SDK Setup (Pro Tools)

1. Download AAX SDK

   Download AAX_SDK_2p3p2.zip from Avid Developer.

2. Extract to Dependencies

   Extract to iPlug2\Dependencies\IPlug\AAX_SDK\

3. Build AAXLibrary

   1. Open AAX_SDK\msvc\AAX_SDK.sln in Visual Studio
   2. Agree to retarget the solution to your current VS version
   3. Right-click AAXLibrary project → Properties
   4. Navigate to: Configuration Properties → C/C++ → Code Generation → Runtime Library
   5. Set:
      • Debug/x64: Multi-threaded Debug (/MTd)
      • Release/x64: Multi-threaded (/MT)
   6. Build both Debug and Release configurations

Windows ARM64EC Support

To build for Windows ARM devices (Surface Pro X, etc.):

cmake -G "Visual Studio 17 2022" -A ARM64EC ..
cmake --build . --config Release

ARM64EC provides native ARM64 performance while maintaining compatibility with x64 plugin hosts.

iOS Installation

1. Install Xcode 15+

   iOS development requires Xcode 15.0 or later with iOS SDK:

   xcode-select --install
   

   Open Xcode and install additional components when prompted.

2. Download iOS Dependencies

   If using Skia graphics on iOS:

   cd Dependencies
   ./download-prebuilt-libs.sh ios
   cd ..
   
3. Configure iOS Build

   Create an iOS build:

   cd Examples/IPlugEffect
   mkdir build-ios && cd build-ios
   cmake -G Xcode -DCMAKE_SYSTEM_NAME=iOS -DIPLUG2_IOS_PLATFORM=OS ..
   

   Open the generated Xcode project:

   open IPlugEffect.xcodeproj
   
4. Configure Code Signing

   In Xcode:

   1. Select the project in the navigator
   2. Select a target (e.g., IPlugEffect-app)
   3. Go to Signing & Capabilities
   4. Select your Apple Developer team
   5. Ensure a valid provisioning profile is selected
5. Build and Run

   1. Select an iOS device or simulator from the scheme menu
   2. Click Run (⌘R) to build and deploy

iOS plugins use the AUv3 (Audio Unit v3) format, which is embedded in a standalone app.

visionOS Installation

1. Install Xcode 15+

   visionOS requires Xcode 15.0 or later with visionOS SDK installed.

   Check available SDKs:

   xcodebuild -showsdks
   

   If xros SDK is not listed, install it via Xcode → Settings → Platforms.

2. Configure visionOS Build

   Create a visionOS build:

   cd Examples/IPlugEffect
   mkdir build-visionos && cd build-visionos
   cmake -G Xcode -DCMAKE_SYSTEM_NAME=iOS -DIPLUG2_IOS_PLATFORM=VISIONOS ..
   open IPlugEffect.xcodeproj
   
3. Configure Code Signing

   Set up signing in Xcode as described in the iOS section.

4. Build and Run

   Select “Apple Vision Pro” or “Apple Vision Pro Simulator” from the scheme menu and click Run.

visionOS support is experimental. Not all IGraphics features may work as expected.

Web/Emscripten Installation

1. Install Emscripten SDK

   Clone and activate the Emscripten SDK:

   git clone https://github.com/emscripten-core/emsdk.git
   cd emsdk
   ./emsdk install latest
   ./emsdk activate latest
   source ./emsdk_env.sh  # On Windows: emsdk_env.bat
   
2. Download WAM SDK

   Return to the iPlug2 directory and download the Web Audio Module SDK:

   cd ../iPlug2/Dependencies/IPlug
   ./download-wam-sdk.sh
   cd ../..
   
3. Build WAM Plugin

   cd Examples/IPlugEffect
   mkdir build-wasm && cd build-wasm
   emcmake cmake -G Ninja -DCMAKE_BUILD_TYPE=Release ..
   ninja IPlugEffect-wam-dist
   

   Output will be in build/out/IPlugEffect/

4. Test Locally

   WAM plugins require HTTPS with specific headers. Use emrun:

   cd ../build/out/IPlugEffect
   emrun --no_emrun_detect index.html
   

   Open the provided URL in your browser.

Web Audio Modules require SharedArrayBuffer, which requires HTTPS and specific COOP/COEP headers. Local testing requires a properly configured server.

VST3 SDK Manual Installation

If the automatic download script fails:

1. Download SDK

   Download the latest VST3 SDK from Steinberg’s website.

2. Extract

   Extract the SDK to Dependencies/IPlug/VST3_SDK/ so the structure looks like:

   Dependencies/IPlug/VST3_SDK/
   ├── base/
   ├── pluginterfaces/
   ├── public.sdk/
   └── README.md
   

Dependency Overview

Below is a summary of required and optional dependencies:

Component	Required	Platforms	Notes
VST3 SDK	For VST3	macOS, Windows	Free from Steinberg
CLAP SDK	For CLAP	macOS, Windows	Free, open source
WAM SDK	For WAM	Web	Free, auto-downloaded
AAX SDK	For AAX	macOS, Windows	Requires Avid account
AUv2/AUv3	For AU	macOS, iOS	Built into Apple SDKs
Skia	Optional	All	High-quality graphics backend
NanoVG	Default	All	Included in iPlug2

Verification

Verify your installation by checking these paths:

macOS

# Check SDKs
ls Dependencies/IPlug/VST3_SDK/
ls Dependencies/IPlug/CLAP_SDK/
ls Dependencies/IPlug/WAM_SDK/

# Check Skia (optional)
ls Dependencies/Build/mac/

# Verify CMake
cmake --version

# Verify Ninja
ninja --version

Windows

# Check SDKs
dir Dependencies\IPlug\VST3_SDK\
dir Dependencies\IPlug\CLAP_SDK\
dir Dependencies\IPlug\WAM_SDK\

# Check Skia (optional)
dir Dependencies\Build\win\

# Verify CMake
cmake --version

# Verify Ninja (optional)
ninja --version

Common Issues

download-iplug-sdks.sh fails on Windows

Use Git Bash instead of Command Prompt or PowerShell:

"C:\Program Files\Git\bin\bash.exe" download-iplug-sdks.sh

Or manually download each SDK from the links above.

CMake can't find Visual Studio

Ensure Visual Studio is properly installed with C++ tools:

cmake -G "Visual Studio 17 2022" -A x64 ..

If this fails, verify Visual Studio installation via Visual Studio Installer.

Xcode Command Line Tools not found

Install or reset the tools:

xcode-select --install
sudo xcode-select --reset

AAXLibrary build fails

• Ensure you retargeted the solution to your Visual Studio version
• Verify runtime library settings are correct (/MT for Release, /MTd for Debug)
• Check that both x64 and ARM64 configurations are set

Emscripten not found

Activate the Emscripten environment:

source /path/to/emsdk/emsdk_env.sh

On Windows:

C:\path\to\emsdk\emsdk_env.bat

iOS build fails with code signing error

• Ensure you have a valid Apple Developer account
• Select your team in Xcode’s Signing & Capabilities
• Use automatic signing for development
• Try building for simulator first (no signing required)

Out-of-Source Setup (Recommended for 2025)

For new projects, consider using iPlug2OOS (Out-Of-Source) which keeps your plugin code separate from the iPlug2 framework:

git clone https://github.com/iPlug2/iPlug2OOS.git
cd iPlug2OOS
git submodule update --init --recursive

iPlug2OOS is the recommended starting point for new projects in 2025, providing better separation and easier updates.

Next Steps

Quickstart Guide

Build your first plugin in minutes with our quickstart tutorial.

API Documentation

Explore the complete API reference.

Examples

Browse example plugins for effects, instruments, and more.

Wiki

Read in-depth guides and tutorials on the iPlug2 Wiki.