Quaternion

Quaternion is a cross-platform desktop IM client for the Matrix protocol. You can find general information about application usage and settings here. See BUILDING.md for building instructions.

Contacts

Most of talking around Quaternion happens in the room of its parent project, Quotient: #quotient:matrix.org. You can file issues at the project's issue tracker. If you find what looks like a security issue, please follow special instructions.

Downloading and installing

The recommended way to install Quaternion is as follows (make sure to read the notes below depending to your environment):

• on GNU/Linux - using your distribution's package manager;
• on macOS - from Homebrew;
• on Windows - from an archive at the project's GitHub Releases page.

The source code is hosted at GitHub.

Requirements

Quaternion 0.0.97.1 needs Qt version 6.4 or higher.

Linux

Quaternion is packaged for many distributions, including various versions of Debian, Ubuntu and OpenSUSE, as well as Arch Linux, NixOS and FreeBSD. A pretty comprehensive up-to-date list can be found at Repology. Popular distributions satisfying the mentioned Qt requirement are Debian 12 (Bookworm), Ubuntu 24.04 (noble), Fedora 39, OpenSUSE Leap 15.6; anything newer than that should be fine, too.

On top of the Quaternion package, you should not normally need to install anything in addition; if something is not working due to a missing dependency, it's a bug in the package - please report it to your distribution's Quaternion packager, not to this repository.

There are also flatpaks for Quaternion available from Flathub. To install, use:

flatpak install https://flathub.org/repo/appstream/io.github.quotient_im.Quaternion.flatpakref

These packages are built with a suitable KDE runtime. You can install them on any distribution that has Flatpak - even if it's older than mentioned above. Please file issues at https://github.com/flathub/io.github.quotient_im.Quaternion if you believe there's a problem specific to the Flatpak package of Quaternion.

Windows

Since there's no established package management on Windows to resolve dependencies, all needed libraries and a C++ runtime are packaged/installed together with Quaternion - except OpenSSL. Unless you already have OpenSSL around (e.g., it is a part of any Qt development installation), you should install it yourself. OpenSSL's Wiki lists a few links to OpenSSL installers. They come in different build configurations; current Quaternion builds distributed from GitHub Releases need OpenSSL 3.x made with/for Visual Studio (not MinGW).

macOS

If you use Homebrew (you should!), brew install quaternion installs Quaternion along with its dependencies. Otherwise, packages published at GitHub Releases come with everything necessary already bundled.

Development builds

Thanks to generous and supportive folks at Cloudsmith who provide free hosting to OSS projects, those who want to check out the latest (not necessarily the greatest, see below) code can find packages produced by continuous integration (CI) in the Quaternion repo there.

A few important notes on these packages in case you're new to them:

• All of them come bundled with fairly recent (not necessarily latest) Qt 6.
• They are only provided for testing; feedback on any release is welcome as long as you know which build you run, but do not expect the developers to address issues in older snapshots.
• In case it's still unclear: these builds are UNSTABLE by default; some may not run at all, and if they do, they may ~~tell you obscenities in your local language, steal your smartphone, and share your private photos~~ scramble the messages you send, interfere with or even break other clients including Element ones, and generally corrupt your account in ways unexpected and hard to fix (all of that actually happened in the past). Do NOT run these builds if you're not prepared to deal with the problems.
• If you understand the above, have your backups in order and are still willing to try things out or just generally help with the project - make sure to /join #quotient:matrix.org and have the URL you downloaded Quaternion from. In case of trouble, ~~show this label to your doctor~~ send the URL to the binary you used in the chat room (you may have to use another client or Quaternion version for that), describe what happened and we'll try to pull you out of it.

If you want to build Quaternion from sources, see BUILDING.md.

Running

Just start the executable in your most preferred way - either from the build directory or from the installed location. If you're interested in tweaking configuration beyond what's available in the UI, read the "Configuration" section further below.

Translation

Quaternion uses Lokalise.co for the translation effort. It's easy to participate: join the project at Lokalise.co; if your language is not there, ask to add it (either in #quotient:matrix.org or in the Lokalise project chat); and start translating! Many languages are still longing for contributors.

Configuration

The only non-trivial command-line option available so far is --locale - it allows you to override the locale Quaternion uses (an equivalent of setting LC_ALL variable on UNIX-based systems). German, Russian, Polish, and Spanish translations are either complete or mostly complete, as of this writing.

Quaternion stores its configuration in a way standard for Qt applications, as described below. It will read and write the configuration in the user-specific location (creating it if non-existent) and will only read the system-wide location with reasonable defaults if the configuration is not found at the user-specific one.

• Linux:
  • user-specific: $HOME/.config/Quotient/quaternion.conf
  • system-wide: $XDG_CONFIG_DIR/Quotient/quaternion or /etc/xdg/Quotient/quaternion
• macOS:
  • user-specific: $HOME/Library/Preferences/im.quotient.quaternion.plist
  • system-wide: /Library/Preferences/im.quotient.quaternion.plist
• Windows: registry keys under
  • user-specific: HKEY_CURRENT_USER\Software\Quotient\quaternion
  • system-wide: HKEY_LOCAL_MACHINE\Software\Quotient\quaternion

ALL settings listed below reside in UI section of the configuration file or (for Windows) registry.

Some settings exposed in the user interface (Settings and View menus) are:

• notifications - a general setting whether Quaternion should distract the user with notifications and how.
  • none suppresses notifications entirely (rooms and messages are still hightlighted but the tray icon is muted);
  • non-intrusive allows the tray icon show notification popups;
  • intrusive (default) adds to that activation of Quaternion window (i.e. the application blinking in the task bar, or getting raised, or otherwise demands attention in an environment-specific way).
• timeline_layout - this allows to choose the timeline layout. If this is set to "xchat", Quaternion will show the author to the left of each message, in an xchat/hexchat style. Any other value will select the "default" layout, with author labels above blocks of messages.
• use_shuttle_dial - Quaternion will use a shuttle dial instead of a classic scrollbar for the timeline's vertical scrolling control. To start scrolling move the shuttle dial away from its neutral position in the middle; the further away you move it, the faster you scroll in that direction. Releasing the dial resets it back to the neutral position and stops scrolling. This is more convenient than the classic scrollbar when you need to move around with bounds of the timeline constantly changing, as is the case of a Matrix timeline (older messages get loaded as you scroll back, and new messages can come from sync too, making the classic scrollbar jump around); with that said, the control is somewhat unconventional and not all people like it. The shuttle dial is enabled by default; set this to false (or 0) to use the classic scrollbar.
• autoload_images - whether full-size images should be loaded immediately once the message is shown on the screen. The default is to automatically load full-size images; set this to false (or 0) to disable that and only load a thumbnail in the timeline (with the full image downloaded after you click "Save as" or "Open" in the context menu) but be aware that if a message doesn't have a thumbnail at all you won't see anything (see also https://github.com/quotient-im/Quaternion/issues/601).
• show_spammy ("Show no-effect activity" in the menu) - when set to false, this setting tries to clean up the timeline from events that don't contribute to conversation in any r