QMPlay2 is available on many Linux distributions through official or community repositories. Installing from a package manager keeps the player updated alongside the rest of your system.
The commands set out below are those given in the project documentation for the common distributions.
Arch Linux and Manjaro
The package resides in the AUR. With an AUR helper such as yay:
yay -S qmplay2-gitFedora
QMPlay2 is supplied through RPM Fusion, which also provides the complete FFmpeg codecs. Enable RPM Fusion free and nonfree first, update the multimedia group, then install:
sudo dnf install qmplay2openSUSE Tumbleweed
Use the Packman repository and switch your multimedia packages to it. Do not mix FFmpeg packages drawn from different repositories.
sudo zypper ar https://ftp.gwdg.de/pub/linux/misc/packman/suse/openSUSE_Tumbleweed Packman
sudo zypper dup --allow-vendor-change --from "Packman"
sudo zypper in QMPlay2Gentoo and Slackware
emerge --ask media-video/qmplay2slpkg install QMPlay2Building with Flatpak
The source tree includes a Flatpak manifest. Install the KDE runtime and SDK, then build with flatpak-builder:
flatpak run org.flatpak.Builder build/flatpak --force-clean --ccache --user --install io.github.zaps166.QMPlay2.Devel.jsonOwners of Intel GPUs may add the VA-API driver extension to enable hardware decoding within Flatpak.
Building from source
Compiling the player yourself is sensible when you want the newest code or a particular set of modules. The principal requirements are:
- CMake 3.16 or newer and the glslc shader compiler
- Qt 5.15.2 or newer, or Qt 6 with the Core5Compat module
- FFmpeg 4.0 or newer (libavformat, libavcodec, libswscale, libavutil, libswresample)
- TagLib 1.11 or newer and libass for tags and styled subtitles
Optional libraries enable further modules: libva for VA-API, libgme and libsidplayfp for chiptunes, libcdio and libcddb for Audio CD, libopenmpt for tracker music, and PipeWire or PulseAudio for audio output.
Remember to fetch the submodules before building:
git submodule update --initA note for ALSA users
If you maintain your own asound.conf or .asoundrc, add defaults.namehint.!showall on. Otherwise certain added devices may not appear in the output list.
Choose a package that fits your distribution
QMPlay2 installation on Linux begins with identifying the distribution, its release and the package source you intend to use. A command written for one distribution should not be pasted into another simply because both systems use Linux. Package names, repositories and dependency versions differ. Check what your package manager offers before introducing an additional repository, and read the proposed changes before approving an installation transaction.
A packaged application usually integrates with your desktop menu and receives updates through the package manager. A source build gives you more control over the compiled features, but also leaves you responsible for build dependencies and later maintenance. Pick one main installation method while testing. Multiple copies can make troubleshooting confusing because the desktop launcher and a terminal command may start different executables. Knowing which copy is running is essential when you compare versions or investigate a missing module.
Read package-manager output before continuing
When you install through a package manager, its output is part of the installation process. Review missing dependencies, repository errors and proposed removals before treating the command as successful. A network failure during repository refresh is different from a package that is not available for your distribution release. Repeating the installation command will not resolve either case unless the underlying cause has changed.
Keep related multimedia libraries consistent. Mixing packages from incompatible sources can cause problems that look like a player defect but actually involve mismatched libraries. If you are using an additional multimedia repository, understand its instructions and the effect of changing package vendors. Do not remove large groups of desktop packages to force one application to install. Cancel an unexpected transaction, read the dependency explanation and choose a package source that fits the system you are maintaining.
Establish a local playback baseline
After installing, start QMPlay2 from the desktop menu and open a local file. Choose a small file that previously worked in another application. Check sound, video, pause and seeking before testing internet playback. This sequence verifies that the desktop session can launch the player and that the basic output path works. It also gives you a reference file for later tests.
If the application launches from a terminal but not from the menu, compare the executable paths and the environment used by each launch method. A custom source installation can take precedence over a packaged version in the terminal while the desktop entry still points elsewhere. If the player starts but produces no sound, check the desktop audio mixer and selected output device. Keep installation, desktop integration and playback troubleshooting separate so that you can act on a specific symptom.
Understand optional modules in source builds
A source build does not automatically include every optional feature. Some capabilities depend on additional libraries being available when the project is configured. Read the configuration summary and build messages to see which components were enabled. If a specialist audio format or output is missing, check its dependency rather than assuming the entire build failed. A player that opens ordinary files may still lack an optional module.
Use a dedicated build directory so that generated files remain separate from the source tree. Keep a record of configuration options and dependency versions when the build succeeds. Fetch the required submodules before compiling, as incomplete source checkout contents can produce errors unrelated to your compiler. When updating the source, review the new build requirements rather than repeatedly applying an old command to a changed project. This makes a custom installation easier to reproduce and easier to remove later.
Permissions, removable drives and sandbox boundaries
A file visible in your file manager is not always accessible to every application in the same way. Check that the drive is mounted and your account can read the file. If a file was copied from another user account or a network share, review its permissions. Avoid running the media player as the system administrator to work around an ordinary file-access problem; correct access to the media location instead.
Sandboxed packaging may introduce another boundary around files, devices and helper tools. If you build or use a Flatpak package, distinguish access restrictions from decoder support. Test a file in an accessible home directory before blaming the format. For a removable drive, confirm that it has not been disconnected or remounted under a new path. When the same file works in one installation method and fails in another, compare permissions and runtime dependencies before making broad changes to the desktop.
Check audio and graphics independently
Linux playback involves the player, the desktop audio service, graphics drivers and the media libraries in the chosen package. Treat them as separate layers when testing. For sound, select the intended device and check whether the desktop has routed the application to a different output. A connected monitor or Bluetooth device can change the available choices. Use familiar headphones or speakers to establish a stable reference.
For video, first confirm that software playback works. Hardware decoding is an additional configuration step and depends on driver support as well as the video format. Test with one known file before experimenting with environment variables or different graphics outputs. On a machine with multiple GPUs, note which device drives the display and which device is selected for decoding. Keep any experimental terminal environment changes local until you understand their effect, rather than adding untested values to every desktop session.
Maintain a clean upgrade and removal process
Use the same package-management route for routine upgrades that you used for installation. If you compiled the application yourself, keep the build directory and installation records until you know how the files are managed. Installing a new package does not necessarily remove a custom executable in a different location. Check the running version after an upgrade so that your test actually uses the expected copy.
Before removing or replacing a working build, preserve configuration you want to keep and save important playlists. Media libraries are separate from the application, but a playlist may refer to paths that change when drives are reorganised. If you switch installation methods, test the replacement before deleting the old build. Keep notes on package source, enabled modules and deliberate settings changes. These details turn a difficult future problem into a comparison between a known working setup and one specific change.
FAQs
Should I use a package or build from source? A package is usually easier to maintain because its dependencies and updates are handled through the distribution. A source build suits users who need particular build options and can maintain the toolchain themselves. The best choice is the one you can keep consistent with the rest of your system.
Why is a package command not found? Check that the command belongs to your distribution and that the required package-management tool is installed. Commands for Arch, Fedora and openSUSE are not interchangeable. An unavailable helper is also different from an unavailable application package. Identify which part failed before trying commands from another distribution.
Why are some multimedia formats unavailable? Inspect the installed multimedia libraries and the modules enabled in your build. Distributions can package optional components differently. Confirm the exact file format and whether another ordinary file works. Do not assume that a filename extension proves which codec is inside or that every package has identical features.
Can I keep packaged and compiled copies together? It is possible, but you need to know which executable each launcher uses. Otherwise an upgrade or settings change may appear ineffective because you are starting another copy. While diagnosing a problem, use one identified installation and record its version so that every test refers to the same application.
Why can the player not open a file on another drive? Check that the drive is mounted, the path is correct and your account has permission to read it. Sandboxed installations may need access to the location as well. Test a readable file in your home directory to distinguish access problems from format or decoder problems.
Do I need hardware acceleration to finish installation? No. Establish reliable local playback first. Hardware decoding can then be configured and compared with software decoding on a supported file. Assess the installation through actual playback and the modules you need, rather than whether every optional graphics setting has already been enabled.
Conclusion
QMPlay2 on Linux is easier to maintain when the installation method matches your distribution and the multimedia libraries remain consistent. Review package-manager changes, verify which executable starts and begin with a familiar local file. For source builds, record optional dependencies and configuration choices so missing features can be traced to a specific component. Check permissions, desktop audio and graphics separately when playback fails. Once a stable setup is working, use the same maintenance route for upgrades and keep useful configuration backups. These habits make both everyday playback and later troubleshooting more predictable.