Installing QLC+

QLC+ is available for multiple platforms including Windows, macOS, Linux, and Raspberry Pi. Follow the instructions below for your operating system.

System Requirements

Before installing QLC+, ensure your system meets the minimum requirements:

Windows
macOS
Linux
Raspberry Pi

Windows System Requirements

Operating System: Windows 10 or newer
Processor: Intel Core i3 or equivalent
RAM: 2GB minimum, 4GB recommended
Graphics: OpenGL 2.0 compatible graphics card
Storage: 200MB free disk space
Additional: Qt 5 or Qt 6 runtime (included in installer)

For DMX USB interfaces, you may need to install specific device drivers depending on your hardware.

Installation Instructions

Windows
macOS
Linux
Raspberry Pi

Installing on Windows

Download the Installer

Visit the QLC+ download page and download the Windows installer:

QLC+ 4: Choose qlcplus-4.x.x-win64.exe for the stable Qt Widgets version
QLC+ 5: Choose qlcplus-5.x.x-win64.exe for the QML version

Select the version based on your Qt installation (Qt 5 or Qt 6).

Run the Installer

Double-click the downloaded .exe file to start the installation wizard.You may see a Windows SmartScreen warning. Click More info and then Run anyway to proceed.

Follow Installation Wizard

Accept the Apache 2.0 license agreement
Choose the installation directory (default: C:\qlcplus)
Select components to install (recommended: all components)
Choose Start Menu folder name
Click Install to begin installation

Complete Installation

Once installation is complete:

Click Finish to exit the installer
Launch QLC+ from the Start Menu or desktop shortcut
The application should start with a new workspace

Install USB Drivers (If Needed)

If you’re using a USB DMX interface, you may need to install device-specific drivers:

FTDI-based devices: Install FTDI VCP drivers
Enttec DMX USB Pro: Usually works with FTDI drivers
Velleman K8062: Install drivers from the manufacturer

Restart your computer after driver installation.

Post-Installation Setup

After installation, configure your DMX output:

Open QLC+ and go to Inputs/Outputs tab
Select your DMX interface in the Output section
Configure the universe mapping for your devices
Test the output using the DMX Monitor

Installing on macOS

Download the DMG

Visit the QLC+ download page and download the macOS disk image:

QLC+ 4: Choose qlcplus-4.x.x-macos.dmg for Intel or Universal build
QLC+ 5: Choose qlcplus-5.x.x-macos.dmg for the QML version

Universal builds support both Intel and Apple Silicon (M1/M2) processors.

Mount the Disk Image

Double-click the downloaded .dmg file to mount it. A Finder window will open showing the QLC+ application.

Install the Application

Drag the QLC+.app (or QLC+ 5.app) icon to the Applications folder in the same window.Wait for the copy operation to complete.

First Launch

Open the Applications folder and double-click QLC+ to launch.You may see a security warning: “QLC+ cannot be opened because it is from an unidentified developer.”To bypass this:

Open System Preferences > Security & Privacy
Click the General tab
Click Open Anyway next to the QLC+ message
Confirm you want to open the application

Disable FTDI Driver (If Needed)

If you’re using an FTDI-based DMX USB interface, you may need to disable macOS’s built-in FTDI driver:

sudo kextunload -b com.apple.driver.AppleUSBFTDI

This command requires administrator privileges and will affect all FTDI devices on your system.

To make this permanent, follow the detailed guide in the QLC+ documentation.

macOS-Specific Notes

QLC+ preferences are stored in ~/Library/Application Support/QLC+
User fixtures and profiles are stored in the same directory
The web interface runs on port 9999 by default

Installing on Linux

QLC+ can be installed on Linux using several methods:

Method 1: Distribution Packages (Recommended)

sudo apt update
sudo apt install qlcplus

Distribution packages may not always have the latest version. Check your distribution’s repository for the available version.

Method 2: AppImage (Latest Version)

Download AppImage

Visit the QLC+ download page and download the AppImage:

wget https://www.qlcplus.org/downloads/qlcplus-4.x.x-x86_64.AppImage

Make Executable

chmod +x qlcplus-4.x.x-x86_64.AppImage

Run QLC+

./qlcplus-4.x.x-x86_64.AppImage

You can move the AppImage to /usr/local/bin or ~/bin for easier access.

Method 3: Build from Source

Install Dependencies

Install required build tools and libraries:

Ubuntu/Debian

sudo apt install build-essential cmake git \
  qt6-base-dev qt6-multimedia-dev qt6-tools-dev \
  libqt6svg6-dev libqt6serialport6-dev \
  libasound2-dev libusb-1.0-0-dev libftdi1-dev

For Qt 5, replace qt6-*-dev with qt5-*-dev packages.

Clone Repository

git clone https://github.com/mcallegari/qlcplus.git
cd qlcplus

Build with CMake

mkdir build && cd build
cmake ..
make -j$(nproc)

To build QLC+ 5 (QML UI) instead:

cmake -Dqmlui=ON ..

Install

sudo make install

This installs QLC+ to /usr by default.

Configure USB Permissions

To use USB DMX interfaces without root privileges, configure udev rules:

Copy udev Rules

If you installed from source:

sudo cp platforms/linux/udev/*.rules /etc/udev/rules.d/

For package installations, rules are usually installed automatically.

Reload udev

sudo udevadm control --reload-rules
sudo udevadm trigger

Add User to Groups

sudo usermod -a -G dialout,plugdev $USER

Log out and back in for group changes to take effect.

Installing on Raspberry Pi

QLC+ runs well on Raspberry Pi 3 and newer models, making it ideal for headless lighting control.

Method 1: Pre-configured Image (Easiest)

Purchase and Download

The official Raspberry Pi image is available from the QLC+ Store.This image includes:

Pre-configured QLC+ installation
Optimized system settings
Web interface enabled by default
Ready for headless operation

Flash to SD Card

Use Raspberry Pi Imager or Etcher to write the image to your microSD card.

Boot and Connect

Insert the SD card into your Raspberry Pi and power it on. Access the web interface at:

http://raspberrypi.local:9999

Method 2: Manual Installation

Install Raspberry Pi OS

Start with a fresh Raspberry Pi OS (32-bit or 64-bit) installation.

Update System

sudo apt update
sudo apt upgrade -y

Install QLC+

sudo apt install qlcplus

Enable Web Interface

Create a startup script to launch QLC+ with web access:

sudo nano /etc/systemd/system/qlcplus.service

Add the following content:

[Unit]
Description=QLC+ Lighting Control
After=network.target

[Service]
Type=simple
User=pi
Environment="DISPLAY=:0"
ExecStart=/usr/bin/qlcplus -w -o /home/pi/workspace.qxw
Restart=on-failure

[Install]
WantedBy=multi-user.target

Enable the service:

sudo systemctl enable qlcplus.service
sudo systemctl start qlcplus.service

Configure Performance

For better performance, disable the desktop environment:

sudo raspi-config

Navigate to System Options > Boot / Auto Login > Console

Raspberry Pi-Specific Tips

Use the GPIO plugin to control simple LED fixtures directly from the Raspberry Pi’s GPIO pins without additional DMX hardware.

The SPI plugin can drive APA102/SK9822 LED strips directly
The UART plugin can output DMX512 from the serial port
Disable Bluetooth if using the UART for DMX: sudo systemctl disable hciuart

Verifying Installation

After installation, verify that QLC+ is working correctly:

Launch QLC+

Open the application from your system’s application menu or command line.

Check Version

Go to Help > About QLC+ to verify the installed version.

Open Inputs/Outputs

Click the Inputs/Outputs tab to see available plugins and universes.

Test with DMX Monitor

Click the Monitor button on the toolbar to open the DMX Monitor and verify the universe display.

Troubleshooting

QLC+ won't start on Windows

Ensure you have installed the correct version matching your Qt installation
Install Microsoft Visual C++ Redistributable if prompted
Check Windows Event Viewer for error messages
Try running as Administrator

DMX interface not detected on Linux

Check USB cable and connection
Verify udev rules are installed: ls /etc/udev/rules.d/*qlc*
Check device permissions: ls -l /dev/ttyUSB* or /dev/ttyACM*
Ensure user is in dialout group: groups $USER
Try unplugging and replugging the device

macOS won't open QLC+ (security warning)

Right-click (or Control-click) the QLC+ application
Select Open from the context menu
Click Open in the security dialog

Alternatively, use System Preferences > Security & Privacy > General > Open Anyway

Build from source fails

Ensure all dependencies are installed
Check CMake version: cmake --version (requires 3.16+)
Verify Qt installation: qmake --version
Check the build log for specific error messages
Consult the GitHub Wiki for platform-specific build instructions

Next Steps

Now that you have QLC+ installed, you’re ready to create your first lighting scene:

Quick Start Guide

Follow our step-by-step guide to set up your first fixture and create a lighting scene

Get Started

Core Concepts

Functions

Fixture Management

Virtual Console

Input/Output

Advanced Features

Installing QLC+

Installing QLC+

System Requirements

Windows System Requirements

macOS System Requirements

Linux System Requirements

Raspberry Pi Requirements

Installation Instructions

Installing on Windows

Post-Installation Setup

Installing on macOS

macOS-Specific Notes

Installing on Linux

Method 1: Distribution Packages (Recommended)

Method 2: AppImage (Latest Version)

Method 3: Build from Source

Configure USB Permissions

Installing on Raspberry Pi

Method 1: Pre-configured Image (Easiest)

Method 2: Manual Installation

Raspberry Pi-Specific Tips

Verifying Installation

Troubleshooting

Next Steps

Quick Start Guide

Build docs developers (and LLMs) love

Get Started

Core Concepts

Functions

Fixture Management

Virtual Console

Input/Output

Advanced Features

​Installing QLC+

​System Requirements

​Windows System Requirements

​macOS System Requirements

​Linux System Requirements

​Raspberry Pi Requirements

​Installation Instructions

​Installing on Windows

​Post-Installation Setup

​Installing on macOS

​macOS-Specific Notes

​Installing on Linux

​Method 1: Distribution Packages (Recommended)

​Method 2: AppImage (Latest Version)

​Method 3: Build from Source

​Configure USB Permissions

​Installing on Raspberry Pi

​Method 1: Pre-configured Image (Easiest)

​Method 2: Manual Installation

​Raspberry Pi-Specific Tips

​Verifying Installation

​Troubleshooting

​Next Steps

Quick Start Guide

Build docs developers (and LLMs) love

Installing QLC+

System Requirements

Windows System Requirements

macOS System Requirements

Linux System Requirements

Raspberry Pi Requirements

Installation Instructions

Installing on Windows

Post-Installation Setup

Installing on macOS

macOS-Specific Notes

Installing on Linux

Method 1: Distribution Packages (Recommended)

Method 2: AppImage (Latest Version)

Method 3: Build from Source

Configure USB Permissions

Installing on Raspberry Pi

Method 1: Pre-configured Image (Easiest)

Method 2: Manual Installation

Raspberry Pi-Specific Tips

Verifying Installation

Troubleshooting

Next Steps