miqt

MIQT

MIQT is MIT-licensed Qt bindings for Go.

This is a straightforward binding of the Qt 5.15 / Qt 6.4+ API using CGO. You must have a working Qt C++ development toolchain to use this Go binding.

These bindings were newly started in August 2024. The bindings are complete for QtCore, QtGui, QtWidgets, Qt SQL, QtMultimedia, QtMultimediaWidgets, QtSpatialAudio, QtPrintSupport, QtSvg, QtScript, QtNetwork, QtWebkit, QtWebChannel, QtWebEngine, QtCharts, QtPositioning, Qt Websockets, QStateMachine, QtUiPlugin/QtUiTools, QML, QScintilla, ScintillaEdit, Qwt, there is subclassing support, and there is a uic/rcc/lupdate implementation. But, the bindings may be immature in some ways. Please try out the bindings and raise issues if you have trouble.

Supported platforms

License

The MIQT Go bindings are licensed under the MIT license.

You must also meet your Qt license obligations.

Made with MIQT

These apps are listed in alphabetical order. Raise an issue or PR to have your app listed here!

• annie-miqt, a GUI application for downloading videos
• autoconfig, uses reflection to edit any Go struct with a Qt interface
• AyanDict - simple yet advanced multi-lingual dictionary using StarDict format
• Benchy, A modern, cross-platform system benchmarking tool
• code_edit, a QSyntaxHighlighter for Go source code
• excel-translator, A lightweight desktop utility for translating Xlsx/Docx files using various translation engines
• jqview, The simplest possible native GUI for inspecting JSON objects with jq
• mdoutliner, Markdown Outliner sample application
• QAnotherRTSP, A lightweight, cross-platform, multi-camera RTSP viewer
• qbolt, a graphical database manager for BoltDB and other databases
• qocker-miqt, a user-friendly GUI application for managing Docker containers
• rsmqt, a cross-platform desktop GUI application for managing RSMQ (Redis Simple Message Queue) instances
• SpeedPing, A lightweight, cross-platform network diagnostics and latency measurement tool
• vnak, a GUI application for Nostr-related debugging, development and plumbing
• WhereAmI, A lightweight desktop waypoint & GPX viewer for exploring and managing your location data
• See more users of the qt5 or qt6 packages

MIQT is also used to produce Qt bindings to other programming languages:

• Cute, Declarative Qt bindings for the Rugo language
• libqt6zig, Qt bindings for Zig and C based on MIQT
• seaqt, Qt bindings for Nim and C based on MIQT

FAQ

Q1. Why are the binaries so big?

Make sure to compile with go build -ldflags "-s -w". This reduces the helloworld example from 43MB to 6MB.

Then, it's possible to reduce the size further with upx --best to 2MB or upx --lzma to 1.4MB.

You can also try miqt-docker native -minify-build to use aggressive CFLAGS.

Q2. Can I release a proprietary, commercial app with this binding?

Yes. You must also meet your Qt license obligations: either use Qt dynamically-linked dll/so/dylib files under the LGPL, or, purchase a Qt commercial license for static linking.

Q3. Why does it take so long to compile?

The first time MIQT is used, your go build would take about 10 minutes. But after that, any go build is very fast.

Go 1.26 is significantly faster.

If you are compiling your app within a Dockerfile, you could cache the build step by running go install github.com/mappu/miqt/qt.

If you are compiling your app with a one-shot docker run command, the compile speed can be improved if you also bind-mount the Docker container's GOCACHE directory: -v $(pwd)/container-build-cache:/root/.cache/go-build. The miqt-docker helper app does this automatically.

See also issue #8.

Q4. How does this compare to other Qt bindings?

MIQT is a clean-room binding that does not use any code from other Qt bindings.

• therecipe/qt is the most mature Qt binding for Go.
  • By default, it works by making IPC calls to a separate C++ binary downloaded at runtime from a site under the maintainer's control. This may be less performant than calling Qt directly.
  • It does not support Go Modules, nor Qt 6
  • Because of the LGPL license, it's extremely difficult to make a proprietary app. See also their issue 259.
• kitech/qt.go is another mature Qt binding for Go.
  • Unfortunately, it's also using the LGPL license. It also does not support Qt 6.
• go-qamel/qamel is an MIT-licensed Qt binding for Go.
  • Unfortunately, it only supports QML, not Qt Widgets.
• ddkwork/qt6 is a precompiled, CGO-free version of Miqt for Windows.
  • Qt 6 (Core, Gui, Widgets) and MIQT are compiled together statically into a single dll, that is dropped to a temporary directory at runtime.

Q5. How does the MIQT Go API differ from the official Qt C++ API?

Most functions are implemented 1:1. The Qt documentation should be used.

Container types:

• The QByteArray, QString, QList, QVector, QMap, QHash types are projected as plain Go []byte, string, []T, and map[K]V. Therefore, you can't call any of the Qt type's methods, you must use some Go equivalent method instead.
• Go strings are internally converted to QString using QString::fromUtf8. Therefore, the Go string must be UTF-8 to avoid mojibake. If the Go string contains binary data, the conversion would corrupt such bytes into U+FFFD (�). On return to Go space, this becomes \xEF\xBF\xBD.
• The iteration order of a Qt QMap/QHash will differ from the Go map iteration order. QMap is iterated by key order, but Go maps and QHash iterate in an undefined internal order.

Memory management:

• Where Qt returns a C++ object by value (e.g. QSize), the binding may have moved it to the heap, and in Go this may be represented as a pointer type. In such cases, a Go finalizer is added to automatically delete the heap object. This means code using MIQT can look basically similar to the Qt C++ equivalent code.

Events and signals:

• The connect(sourceObject, sourceSignal, targetObject, targetSlot) is projected as targetObject.onSourceSignal(func()...).
• You can also override virtual methods like PaintEvent in the same way. Your callback func() receives super() as a first argument that can be used to call the base class implementation.

Class pointers:

• Qt class inherited types are projected as a Go embedded struct. For example, to pass a var myLabel *qt.QLabel to a function taking only the *qt.QWidget base class, write myLabel.QWidget.
• When a Qt subclass adds a method overload (e.g. QMenu::addAction(QString) vs QWidget::addAction(QAction*)), the base class version is shadowed and can only be called via myQMenu.QWidget.AddAction(QAction*).
• A MIQT pointer points to a Go struct, not to the raw C++ Qt widget class. Therefore QTabWidget.CurrentWidget() == MyTab will never compare equal because CurrentWidget() created a new Go struct wrapping the same C++ pointer. You can compare QTabWidget.CurrentIndex(), or, you can use: QTabWidget.CurrentWidget().UnsafePointer() == MyTab.UnsafePointer().

Multithreading:

• The Go runtime migrates goroutines between OS threads, but Qt expects fixed OS threads to be used for each QObject. When you first call qt.NewQApplication in MIQT, that will be considered the Qt main thread and will automatically signal the Go runtime to bind to a fixed OS thread using runtime.LockOSThread().
• When accessing Qt objects from inside another goroutine, it's safest to use (qt6/mainthread).Wait() or Start() to access the Qt objects from Qt's main thread.

Android:

• A QFileDialog may return a filepath of the form content://.... Such paths can be opened with qt.QFile but not with Go os.Open(); you can pass the handle to Go using os.NewFile(QFile.Handle(), "name").

Some C++ idioms that were difficult to project were omitted from the binding. But, this can be improved in the future.

Q6. Can I use Qt Designer and the Qt Resource system?

MIQT has a custom implementation of Qt uic and rcc tools, to allow using Qt Designer for form design and resource management. After running the miqt-uic and miqt-rcc tools once, you can rebuild any changes using the convenient go generate command.

To install the tools, run:

go install github.com/mappu/miqt/cmd/miqt-uic@latest
go install github.com/mappu/miqt/cmd/miqt-rcc@latest

The tools are installed into your ~/go/bin directory. You could add this directory to your $PATH.

Q7. How can I point MIQT to use a custom Qt install location?

MIQT uses pkg-config to find all used Qt libraries. Every Qt library should have a definition file in .pc format, which provides CGO with the necessary CXXFLAGS/LDFLAGS. Your Qt development environment already included the necessary .pc definition files.

You can use the PKG_CONFIG_PATH environment variable to override where CGO looks for .pc files. Read more »

After changing the environment variable, you may need to run go clean -cache to ensure the next go build properly rebuilds MIQT against the changed Qt target. Otherwise, a previous Qt installation could be targeted from the cached build data.

Q8. How can I upgrade a MIQT app from Qt 5 to Qt 6?

The import path changes from github.com/mappu/miqt/qt to github.com/mappu/miqt/qt6, but most basic classes are the same.

You can update all imports by running find . -type f -name .go -exec sed -i 's_"github.com/mappu/miqt/qt"_qt "github.com/mappu/miqt/qt6"_' {} \;

Q9. How can I add bindings for another Qt library?

Fork this repository and add your library to the genbindings/config-libraries file. Read more »

Q10. Is there an easy build tool?

You can use the ordinary go get and go build commands. To help with cross-compilation, you can use the optional miqt-docker tool. Read more »

Building

Linux (native)

Tested with Debian 12 / Qt 5.15 + 6.4 / GCC 12

Tested with Fedora 40 + 41 / Qt 6.7 + 6.8 / GCC 14

1. Install dependencies

For dynamic linking, with the system Qt (Qt 5):

# Debian / Ubuntu (Mini