SingleApplication, the Qt replacement that keeps one primary instance and talks to it

The single instance mechanism, and what it costs

The mechanism is straightforward and worth understanding before you adopt it. The library sets up a QLocalServer and a QSharedMemory block. The first instance of your application is the primary instance: it checks whether the shared memory block exists, and if it does not, it starts a QLocalServer and listens for connections. Each subsequent instance checks for the same shared memory block, and if it finds one, it connects to the local server to notify the primary that a new instance has been started, after which it terminates with status code 0. The primary instance emits the instanceStarted() signal when it detects that, which is where your application hooks in. Two details are worth noting. The library uses `stdlib` to terminate the program with the exit() function, so the secondary instance does not unwind the stack normally, and the detection relies on a shared memory segment surviving while the primary is alive, which is what makes it a system-wide check rather than a per-process one. Using the class is otherwise like using any other QCoreApplication derived class.

#include <QApplication>
#include <SingleApplication.h>

int main( int argc, char* argv[] )
{
    SingleApplication app( argc, argv );

    return app.exec();
}

The class name is decided by a macro at build time

SingleApplication inherits from whatever QCoreApplication or QGuiApplication class you name in the QAPPLICATION_CLASS macro, with QCoreApplication as the default. That is a deliberate design choice to avoid vendoring two parallel class hierarchies, and it is also the sharpest edge in the API. If your application is a GUI app and you leave the macro at its default, the class you get is a QCoreApplication derivative, which does not give you the GUI facilities you expect from a widget application. The documentation says so more than once: do not forget to specify which application class your app is using if it is not QCoreApplication. The examples directory carries several working cases, including a basic one, a calculator, sending arguments between instances, a separate object variant, and a Windows raise widget example, which is a good way to see the intended usage patterns.

include(singleapplication/singleapplication.pri)
DEFINES += QAPPLICATION_CLASS=QApplication

Getting the source in: submodule, qmake or CMake

The recommended way to include the library is as a git submodule, and the build system integration comes in two flavours. With qmake you include the singleapplication.pri file in your .pro file and set the class macro as a define. With CMake you add the subdirectory and link against the SingleApplication::SingleApplication target, passing the class as a cached string variable so it can be chosen per project. The documentation then raises a fair objection: vendoring the repository as a submodule, or copying the source in, might not be ideal when using CMake, and it offers CMake's FetchContent module as the alternative, available since version 3.11. The FetchContent example declares the repository and a git tag, makes it available to the build, then uses find_package as usual and links the resulting target. The tag in the example is master, with a specific commit hash given in a comment as the pinned alternative.

set(QAPPLICATION_CLASS QApplication CACHE STRING "Inheritance class for SingleApplication")
add_subdirectory(src/third-party/singleapplication)
target_link_libraries(${PROJECT_NAME} SingleApplication::SingleApplication)

Freestanding mode, and an honest admission about it

The freestanding mode is the more interesting part of the design, because it is where the author documents a compromise rather than hiding it. In this mode SingleApplication is not derived from a Qt application class at all. You create a normal Qt application instance and then a separate SingleApplication object beside it, and the arguments to the latter are discarded. The documentation calls this a workaround, and says so directly: with the discarded arguments and a class name that sounds like a Qt application class without being one, it looks like a workaround, and it is one. The reason it exists is compatibility. Moving the mode enum into a separate SingleManager class would be the clean design, but that would move SingleApplication::Mode to SingleManager::Mode, which is a breaking change, so it cannot happen in the 3.x line. The mode is enabled by setting QAPPLICATION_CLASS to FreeStandingSingleApplication, a fake base class with no additional functionality. The payoff is that you can build a precompiled static library, because the macro no longer has to pick your application class at build time, and you can hold the object in a std::optional to decide at runtime whether you want the behaviour at all.

int main( int argc, char* argv[] )
{
    // The normal application class with a type of your choice
    QApplication app( argc, argv );

    // Separate single application object (argc and argv are discarded)
    SingleApplication single( argc, argv /*, options ...*/ );

    // Do your stuff

    return app.exec();
}

Building a precompiled freestanding library

The freestanding mode exists partly so the library can be shipped as a binary. The build sets the class macro to the free standing variant and turns on the install option, then builds and installs as usual, which produces a static library with CMake config files. Consuming it is then the ordinary find_package and target_link_libraries pair, and the documentation notes that the QAPPLICATION_CLASS macro is eliminated during the CMake install, so it does not leak into your project. The three-line build invocation is the whole procedure, and the requirement of a precompiled version is what makes the separate-object arrangement worth its awkwardness: an application that wants single instance behaviour can take a runtime decision on whether to instantiate the object, rather than being forced into one behaviour at compile time.

cmake -DQAPPLICATION_CLASS=FreeStandingSingleApplication -DSINGLEAPPLICATION_INSTALL=ON SingleApplicationDir
cmake --build .
cmake --install

Responding to the second launch

The instanceStarted() signal is the whole reason the primary instance survives a second launch instead of being a passive flag. The documented use is to raise your window when a new instance was started, and the example connects the signal to QWindow::raise on a QWindow instance. For a user who double-clicks your app again and the window does nothing, this is the piece you implement. There is also a convenience for the awkward part of wiring it up from elsewhere in your program: SingleApplication::instance() returns the SingleApplication instance so you can bind to its signals from any code path, rather than having to thread the object through your constructors. The one platform caveat is significant enough to be called out separately. On Windows the ability to bring application windows to the foreground is restricted by the operating system, and the project keeps a separate Windows.md document with the specific implementations and a workaround. Any application that must reliably pop up when launched a second time needs to read that file before it ships.

QObject::connect(
    &app,
    &SingleApplication::instanceStarted,
    &window,
    &QWindow::raise
);

Maintenance and licence

The project is not archived, and the last push to the repository was on 2026-06-16, which is the same day as release v3.5.6. The release before that, v3.5.5, is from 2026-06-10, and v3.5.4 goes back to 2025-10-08. The cadence is therefore irregular but active, with a burst of releases in June 2026 after a longer quiet period. The repository is a C++ project with a conventional layout: singleapplication.h and singleapplication.cpp as the implementation, singleapplication_p.h and singleapplication_p.cpp for the platform-specific parts, a singleapplication.pri for qmake consumers, a CMakeLists.txt at the root, a SingleApplicationConfig.cmake.in template for the installed package, a FreeStandingSingleApplication directory for the fake base class, a Windows.md document, an examples directory and a CHANGELOG.md. The licence identifier in the repository metadata is a custom one that GitHub cannot classify, so the LICENSE file at the root is what governs, and anyone vendoring this code into a commercial product should read it before doing so.

Editorial conclusion

Adopt SingleApplication if you are writing a Qt desktop application that should behave like a single-instance tool, for example a chat client, a media player or a configuration dialog, and skip it if you need several instances to coexist on purpose, since the whole point of the class is to close them. Verify three things before you integrate it: that you set QAPPLICATION_CLASS to match your application, since the default is QCoreApplication and a GUI app left at the default will not behave as expected; which build integration you want, because the qmake and CMake paths differ and the macro is evaluated at build time in the normal mode; and that you read the Windows note, because raising a window to the foreground is restricted on Windows and the workaround is described separately.

Frequently asked questions

Official sources

1. Issues
2. itay-grudev/SingleApplication on GitHub
3. Project website
4. README
5. Releases