Installing QLC+

Step-by-step installation instructions for QLC+ on Linux, Windows, macOS, and Raspberry Pi

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

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.

macOS

macOS System Requirements

• Operating System: macOS 10.12 (Sierra) or newer
• Processor: Intel or Apple Silicon (M1/M2)
• RAM: 2GB minimum, 4GB recommended
• Graphics: Metal-compatible graphics
• Storage: 200MB free disk space

On macOS, you may need to disable Apple’s FTDI driver for certain DMX USB interfaces. See the troubleshooting section below.

Linux

Linux System Requirements

• Operating System: Modern Linux distribution (Ubuntu 20.04+, Fedora 35+, Debian 11+, etc.)
• Processor: Intel Core i3 or equivalent
• RAM: 2GB minimum, 4GB recommended
• Graphics: OpenGL 2.0 compatible
• Storage: 200MB free disk space
• Dependencies: Qt 5.15+ or Qt 6.x, libasound2 (ALSA), libusb

Linux users will need to configure udev rules for USB DMX interfaces to allow non-root access.

Raspberry Pi

Raspberry Pi Requirements

• Model: Raspberry Pi 3 or newer (Pi 4/5 recommended)
• Operating System: Raspberry Pi OS (Bookworm or newer)
• RAM: 1GB minimum, 2GB+ recommended
• Storage: 4GB microSD card minimum, 16GB+ recommended
• Additional: Official Raspberry Pi image available from QLC+ store

QLC+ offers a pre-configured Raspberry Pi image that’s ready to use for headless lighting control applications.

Installation Instructions

Windows

Installing on Windows

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

2. 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.

3. 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
4. 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
5. 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:

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

macOS

Installing on macOS

1. 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.

2. Mount the Disk Image

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

3. 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.

4. 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:

   1. Open System Preferences > Security & Privacy
   2. Click the General tab
   3. Click Open Anyway next to the QLC+ message
   4. Confirm you want to open the application
5. 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

Linux

Installing on Linux

QLC+ can be installed on Linux using several methods:

Method 1: Distribution Packages (Recommended)

Ubuntu/Debian

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)

1. Download AppImage

   Visit the QLC+ download page and download the AppImage:

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

   chmod +x qlcplus-4.x.x-x86_64.AppImage
   
3. 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

1. 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.

2. Clone Repository

   git clone https://github.com/mcallegari/qlcplus.git
   cd qlcplus
   
3. Build with CMake

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

   To build QLC+ 5 (QML UI) instead:

   cmake -Dqmlui=ON ..
   
4. 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:

1. 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.

2. Reload udev

   sudo udevadm control --reload-rules
   sudo udevadm trigger
   
3. Add User to Groups

   sudo usermod -a -G dialout,plugdev $USER
   

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

Raspberry Pi

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)

1. 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
2. Flash to SD Card

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

3. 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

1. Install Raspberry Pi OS

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

2. Update System

   sudo apt update
   sudo apt upgrade -y
   
3. Install QLC+

   sudo apt install qlcplus
   
4. 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
   
5. 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:

1. Launch QLC+

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

2. Check Version

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

3. Open Inputs/Outputs

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

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

1. Right-click (or Control-click) the QLC+ application
2. Select Open from the context menu
3. 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