Repository files navigation

Syncthing Tray provides a tray icon and further platform integrations forSyncthing. Checkout thewebsite for an overview andscreenshots.

The following integrations are provided:

• Tray application (using the Qt framework)
• Context menu extension for theDolphin file manager
• Plasmoid forKDE Plasma
• Command-line interface
• Qt-ish C++ library

Checkout theofficial forum thread for discussionsand announcement of new features.

This README document currently serves as the only and main documentation. So read on for details aboutthe configuration. If you are not familiar with Syncthing itself already you should also have a look attheSyncthing documentation as this README is only going to cover theSyncthing Tray integration.

Issues can be created on GitHub but please check thedocumentation on known bugs and workarounds before.

Syncthing Tray works with Syncthing v1 (and probably v0). Note that Syncthing Tray is maintained, andupdates will be made to support future Syncthing versions as needed.

Official binaries are provided for Windows (for i686, x86_64 and aarch64) and GNU/Linux (for x86_64) and can bedownload from thewebsite and therelease section on GitHub. This is only a fraction ofthe available downloads, though. I also provide further repositories for some GNU/Linux distributions. There arealso binaries/repositories provided by other distributors. For a list with links, checkout the"Download" section of this document.

Syncthing Tray is known to work under:

• Windows 10 and 11
• KDE Plasma
• Openbox using lxqt/LXDE or using Tint2
• GTK-centered desktops such as Cinnamon, GNOME and Xfce (with caveats, see remarks below)
• COSMIC (only simple tray menu works, see remarks below)
• Awesome
• i3
• macOS
• Deepin Desktop Environment
• Sway/Swaybar/Waybar (with caveats, see remarks below)
• Android (still experimental and in initial development)

This doesnot mean Syncthing Tray is actively tested on all those platforms ordesktop environments.

For Plasma 5 and 6, there is in addition to the Qt Widgets based version also a "native"Plasmoid. Note that the latest version of the Plasmoid generally also requires thelatest version of Plasma 5 or 6 as no testing on earlier versions is done. Use the QtWidgets based version on other Plasma versions. Checkout the"Configuring Plasmoid" section for further details.

On GTK-centered desktops have a look at theArch Wikifor how to achieve a more native look and feel. Under GNOME one needs to installan extension for tray icon support (unlessone's distribution already provides such an extension by default).

Limitations of your system tray might affect Syncthing Tray. For instance when using the mentioned GNOMEextension the Syncthing Tray UI shown in thescreenshots is only shown bydouble-clickingthe icon. If your system tray is unable to show the Syncthing Tray UI at all like on COSMIC you can still useSyncthing Tray for the tray icon and basic functionality accessible via the menu.

Note that under Wayland-based desktops there will be positioning issues. The Plasmoid is not affectedby this, though.

Thedocumentation on known bugs and workaroundscontains further information and workarounds for certain platform-specific issues like the positioning issues underWayland.

Documentation on how to use Syncthing Tray on Android can be found in aseparate document.

• Provides quick access to most frequently used features but does not intend to replace the official web-based UI
  • Check state of folders and devices
  • Check current traffic statistics
  • Display further details about folders and devices, like last file, lastscan, items out of sync, ...
  • Display ongoing downloads
  • Display Syncthing log
  • Trigger re-scan of a specific folder or all folders at once
  • Open a folder with the default file browser
  • Pause/resume a specific device or all devices at once
  • Pause/resume a specific folder
  • View recent history of changes (done locally and remotely)
• Shows "desktop" notifications
  • The events to show notifications for can be configured
  • Uses Qt's notification support or a D-Bus notification daemon directly
• Provides a wizard for a quick setup
• Allows monitoring the status of the Syncthing systemd unit and to start and stop it (see section"Configuring systemd integration")
• Provides an option to conveniently add the tray to the applications launched when the desktop environment starts
• Can launch Syncthing automatically when started and display stdout/stderr (useful under Windows)
• Browsing the global file tree and selecting items to add to ignore patterns.
• Provides quick access to the official web-based UI
  • Can be opened as regular browser tab
  • Can be opened in a dedicated window utilizing either
    • Qt WebEngine/WebKit
    • the "app mode" of a Chromium-based browser (e.g. Chrome and Edge)
• Allows switching quickly between multiple Syncthing instances
• Also features a simple command line utilitysyncthingctl
  • Check status
  • Trigger rescan/pause/resume/restart
  • Wait for idle
  • View and modify raw configuration
  • Supports Bash completion, even for folder and device names
• Also bundles a KIO plugin which shows the status of a Syncthing folder and allows to trigger Syncthing actionsin the Dolphin file manager
  • Rescan selected items
  • Rescan entire Syncthing folder
  • Pause/resume Syncthing folder
  • See also thescreenshots
• Allows building Syncthing as a library to run it in the same process as the tray/GUI
• English and German localization

Syncthing Tray doesnot launch Syncthing itself by default. There should be no interference with your existingSyncthing installation. You might consider different configurations:

• If you're happy how Syncthing is started on your system so far just tell Syncthing Tray to connect to your currentlyrunning Syncthing instance in the settings. If you're currently starting Syncthing via systemd you might considerenabling the systemd integration in the settings (see section "Configuring systemd integration").
• If you would like Syncthing Tray to take care of starting Syncthing for you, you can use the Syncthing launcheravailable in the settings. Note that this isnot supported when using the Plasmoid.
  • The Linux and Windows builds provided in therelease section on GitHubcome with a built-in version of Syncthing which you can consider to use. Note that the built-in version of Syncthingwill be only updated when you update Syncthing Tray (either manually or via the its updater). The update feature ofSyncthing itself is not available this way.
  • In any case you can simply point the launcher to the binary of Syncthing which you have to download/install separately.This way Syncthing can be (but also has to be) updated independently of Syncthing Tray, e.g. using Syncthing's ownupdate feature.
  • Checkout the "Configuring the built-in launcher" section for further details.
• It is also possible to let Syncthing Tray connect to a Syncthing instance running on a different machine.

Note that the experimental UI tailored for mobile devices is more limited. So far it can only start a built-inversion of Syncthing or connect to an externally started Syncthing instance. It will set a custom config/datadirectory for Syncthing so any Syncthing instance launched via the mobile UI will not interfere with existing setups.

Checkoutthe website for obtaining the executableor package. This README also lists more options and instructions for building from sources.

If you are using one of the package manager options you should follow the usual workflow of that package manager.

Otherwise, you just have to extract the archive and launch the contained executable. Especially on Windows, pleaseread the notes on the website before filing any issues. Note that automatic updates haven't been implemented yet.To uninstall, just delete the executable again.

For further cleanup you may ensure that autostart is disabled (to avoid a dangling autostart entry). You may alsodelete the configuration files (see "Location of the configuration file"section below).

You need to configure how Syncthing Tray should connect to Syncthing itself. The previoussection "Does this launch or bundle Syncthing itself…" mentions available options. Additionally,a wizard is shown on the first launch which can guide though the configuration for commonsetups. If you have dismissed the wizard you can still open it at any point via a button on thetop-right corner of the settings dialog.

It may be worthwhile to browse though the pages of the configuration dialog to tweak SyncthingTray to your needs, e.g. to turn off notification you may find annoying.

The configuration file is usually located under~/.config/syncthingtray.ini on GNU/Linux andunder%appdata%\syncthingtray.ini on Windows. For other platforms and further details,checkout theQt documentation(Syncthing Tray uses the "IniFormat"). For portable installations it is also possible to placean empty file calledsyncthingtray.ini directly next to the executable.

You may remove the configuration file under the mentioned location to start from scratch.

Note that this only counts for Syncthing Tray. For Syncthing itself, checkoutits own documentation.

The Plasmoid is using the same configuration file but in addition also Plasma's configurationmanagement for settings specific to a concrete instance of the Plasmoid.

The experimental UI tailored for mobile devices is using a distinct configuration which islocated under~/.config/Martchus/Syncthing Tray on GNU/Linux and/storage/emulated/0/Android/data/io.github.martchus.syncthingtray on Android and%appdata%\Martchus\Syncthing Tray on Windows. The configuration and database of Syncthingitself are also located within this directory when Syncthing is launched via the mobile UI.

When using a Unix domain socket as Syncthing GUI address (e.g. by starting Syncthing withparameters like--gui-address=unix://%t/syncthing.socket --skip-port-probing) you need tospecify the path to the socket as "Local path" in the advanced connection settings. Thissetting requires Qt 6.8 or higher. You still need to provide the "Syncthing URL" using theunix+http as scheme (e.g.unix+http://127.0.0.1:8080 where the host and port are notactually used). The web view will not work with this, though.

This section doesnot apply to theAndroid app, thePlasmoid and theDolphin integration.

Syncthing Tray is a single-instance application. So if you try to start a second instance thesecond process will only pass arguments to the process that is already running and exit. Thisis useful as is prevents one from accidentally launching two Syncthing instances at the sametime via the built-in Syncthing launcher. It also allows showing the triggering certainactions via certain launch options, see "Configuring hotkeys" fordetails.

Besides that there are a few other notable launch options:

• --connection [config name] …:Shows tray icons for the specified connection configurations (instead of just a single trayicon for the primary connection configuration). Syncthing Tray will still behave as asingle-instance application so a single process will handle all those tray icons and thebuilt-in Syncthing launcher will launch Syncthing only once.
• --replace:Changes the single-instance behavior so that the already running process is existing andthe second process continues to run. This is useful to restart Syncthing Tray afterupdating.
• --new-instance:Disables the single-instance behavior. This can be useful to run two instances ofSyncthing itself via the built-in launcher in parallel. This only makes sense if thosetwo Syncthing instances use a different configuration/database which can be achieved withaportable configuration.
• --single-instance:Avoids the creation of a second tray icon if Syncthing Tray is already running. (Withoutthis option, Syncthing Tray will still show another tray icon despite its single-instancebehavior.)
• --help:Prints all launch options.

Those were just the options of the tray application. Checkout the"Using the command-line interface" section for anoverview of available tooling for the command-line.

The Plasmoid requires installing Syncthing Tray via distribution-specific packaging. It isnot available via the generic GNU/Linux download or the Flatpak. Checkout the relevant noteson thedownloads page foravailable options and details on package names. For further information about supported versionsof Plasma, checkout the "Supported platforms" section.

The built-in Syncthing launcher is not available in the Plasmoid as it is recommended to rely onthe systemd integration instead.

Once installed, Plasma might need to be restarted for the Plasmoid to be selectable.

The Plasmoid can be added/shown in two different ways:

1. It can be shown as part of the system tray Plasmoid.
   • This is likely the preferred way of showing it and may also happen by default.
   • Whether the Plasmoid is shown as part of the system tray Plasmoid can be configuredin the settings of the system tray Plasmoid. You can access the settings of thesystem tray Plasmoid from its context-menu which can be opened by right-clicking onthe arrow for expanding/collapsing.
   • The list of entries in the system tray Plasmoid settings might show aninvalid/disabled entry for Syncthing in some cases. There should always neverthelessalso be a valid entry which can be used. See therelated issue for details.
   • This way it is also possible to show the icon only in certain states by choosing toshow it only when important and selecting the states in the Plasmoid's settings.
   • Configuring the size has no effect when the Plasmoid is displayed as part of thesystem tray Plasmoid.
2. It can be added to a panel or the desktop like any other Plasmoid.Note that underrecent Plasma versions the configuration no longer seems to be stored persistently.So I recommend using the previous option or following therelated issue for workarounds.

This allows you to add multiple instances of the Plasmoid but it is recommended to pickonly one place. For that it makes also most sense to ensure the autostart of thestand-alone tray application is disabled. Otherwise you would end up having two iconsat the same time (one of the Plasmoid and one of the stand-alone application).

The Plasmoid cannot be closed via its context menu like the stand-alone application.Instead, you have to disable it in the settings of the system tray Plasmoid as explainedbefore. If you have added the Plasmoid to a panel or the desktop you can delete it likeany other Plasmoid.

In case the Plasmoid won't show up, checkout the"Troubleshooting KDE integration" section below forfurther help.

The Dolphin integration can be enabled/disabled in Dolphin's context menu settings. It willread Syncthing's API key automatically from its config file. If your Syncthing config file isnot in the default location you need to select it via the corresponding menu action.

The next section explains what it is good for and how to use it. If it doesn't work on yoursystem please read the subsequent sections as well before filing an issue.

With the system configured correctly and systemd support enabled at build-time the followingfeatures are available:

• Starting and stopping the systemd unit of Syncthing
• Consider the unit status when connecting to the local instance to prevent connection attemptswhen Syncthing isn't running anyways
• Detect when the system has just been resumed from standby to avoid the "Disconnect"notification in that case

However, these features are optional. To use them they must be enabled in the settings dialogfirst.

It is recommended to enable "Consider unit status …". Note that Syncthing might still not be immediatelyready to serve API requests when the systemd unit turns active. Hence it is still required to configurea re-connect interval. The re-connect interval will only be in effect while the systemd unit is active.So despite the re-connect interval there will be no connection attempts while the systemd unit isinactive. That's all the systemd integration can optimize in that regard.

Be aware that Syncthing Tray assumes by default that the systemd unit is auser unit. If you are usinga regular system-wide unit (including those ending with…@username) you need to enable the"System unit" checkbox in the settings. Note that starting and stopping the system-wide Syncthingunit requires authorization (systemd can ask through PolicyKit).

The communication between Syncthing Tray and systemd is implemented using systemd's D-Bus service.That means systemd's D-Bus service (which is calledorg.freedesktop.systemd1) must be running onyour D-Bus. Foruser units the session D-Bus isrelevant and for regular units (including those ending with…@username) the system D-Bus is relevant.

It seems that systemd's D-Bus service is only available when D-Bus itself is started via systemd. Thatis by default the case under Arch Linux and openSUSE and likely most other modern distributions whereit is usually started via "socket activation" (e.g./usr/lib/systemd/user/dbus.socket for the sessionD-Bus).

All of this counts for the session D-Busand for the system D-Bus although the startup of the sessionD-Bus can be screwed up particularly easy. One easy way to screw it up is to start a second instance ofthe session D-Bus manually e.g. viadbus-run-session. When starting the session D-Bus this way thesystemd integration willnot work and you will likely end up with two session D-Bus processes. It isalso worth noticing that you donot need to set theDBUS_SESSION_BUS_ADDRESS variable manuallybecause the systemd filedbus.socket should take care of this.

Note that the Plasma Wayland session screwed things up in the way I've described. This has been fixed withOnly spawn dbus-run-session if there isn't a session alreadybut this change might not be available on older distributions.

The built-in launcher can be accessed and configured within the settings dialog. It isnot availablein the Plasmoid. It allows you to launch Syncthing

1. as anexternal process by leaving "Use built-in Syncthing library"unchecked.
   • When launching Syncthing this way you have to specify the path to an executable, e.g. one youhave downloaded from theupstream Syncthing website. It is alsopossible use the Syncthing version built into Syncthing Tray by pointing it to the Syncthing Trayexecutable and specifying the argumentssyncthing serve.
   • When launching Syncthing as external process Syncthing Tray does not interfere withSyncthing's configuration for lowering the priority.
2. as part of the Syncthing Tray UI process by checking "Use built-in Syncthing library".
   • This will always use the Syncthing version built into Syncthing Tray.
   • Launching Syncthing as part of the UI process will interfere withSyncthing's configuration for lowering the priority.You should therefore avoid using this configuration option or start Syncthing as external processinstead. Otherwise the configuration option might have no effect or will affect the UI of SyncthingTray as well causing it to become slow/unresponsive.
   • This option might not be available on your build of Syncthing Tray, e.g. it is disabled on thepackages I provide for GNU/Linux distributions as it makes most sense to use thedistribution-provided version of Syncthing there.

It is recommended to enable "Consider process status …". Note that Syncthing might not be immediatelyready to serve API requests when started. Hence it is still required to configure a re-connect interval.The re-connect interval will only be in effect while the Syncthing process is running. So despite there-connect interval there will be no connection attempts while the Syncthing process is not running.

Use the same approach as for launching an arbitrary application via a hotkey in your graphicalenvironment. Make it invoke

• syncthingtray --trigger to show the Qt Widgets based tray menu.
• syncthingtray --webui to show the web UI.
• syncthingctl [...] to trigger a particular action. Seesyncthingctl -h for details.

The Plasmoid can be shown via a hot-key as well by configuring one in the Plasmoid settings.

Syncthing Tray provides two command-line interfaces:

• The separate executablesyncthingctl allows to interact with a running instance of Syncthing totrigger certain actions like rescans, editing the Syncthing config and more. It complementsSyncthing's own command-line interface. Invokesyncthingctl --help for details.
• The GUI/tray executablesyncthingtray also exposes a command-line interface to interact witha running instance of the GUI/tray. Invokesyncthingtray --help for details. Additional remarks:
  • If Syncthing itself is built into Syncthing Tray (like the Linux and Windows builds found inthe release-section on GitHub) then Syncthing's own command-line interface is exposed viasyncthingtray as well.
  • On Windows, you'll have to use thesyncthingtray-cli executable to see output in the terminal.
  • The experimental mobile UI can be launched on the desktop with theqt-quick-gui sub-commandwhen Syncthing Tray was built with support for it.

Checkout thedownload section on the website for an overview.Keep reading here for a more detailed list.

See therelease section on GitHub.

• Arch Linux
  • for PKGBUILDs checkoutmy GitHub repository orthe AUR
  • there is also abinary repository
• Tumbleweed, Leap, Fedora
  • RPM *.spec files and binaries are available via openSUSE Build Service
    • remarks
      • Be sure to add the repository that matches the version of your OS and to keep itin sync when upgrading.
      • The linked download pages might be incomplete, use the repositories URL for a fulllist.
      • Old packages might remain as leftovers when upgrading and need to be cleaned upmanually, e.g.zypper rm libsyncthingconnector1_1_20 libsyncthingmodel1_1_20 libsyncthingwidgets1_1_20.
    • latest releases:download page,repositories URL,project page
    • Git master:download page,repositories URL,project page
  • available split packages
    • syncthingtray/syncthingtray-qt6: Qt-widgets based GUI
    • syncthingplasmoid/syncthingplasmoid-qt6: applet/plasmoid for Plasma desktop
    • syncthingfileitemaction/syncthingfileitemaction-qt6: Dolphin/KIO integration
    • syncthingctl/syncthingctl-qt6: command-line interface
• Debian ≥12 "bookworm" and its derivatives (Ubuntu, Pop!_OS, etc, but not Neon)
  • sudo apt install syncthingtray-kde-plasma if using KDE Plasma; otherwise,sudo apt install syncthingtray.
  • Installation from a Software Centre such asGNOME Software orDiscover should be possible as well.
• Exherbo
  • packages for my other project "Tag Editor" and dependencies could serve as a base and are providedbythe platypus repository
• Gentoo
  • there is a package inCase_Of's overlay
• NixOS
  • the package syncthingtray is available from the official repositories
• Void Linux
  • available as split packages from theofficial repositories:
    • syncthingtray: GUI and command-line interface
    • syncthingtray-plasma: applet/plasmoid for Plasma desktop
    • syncthingtray-dolphin: Dolphin/KIO integration
• Other GNU/Linux systems
  • for generic, self-contained binaries checkout therelease section on GitHub
    • Requires glibc>=2.26, OpenGL and libX11
      • openSUSE Leap 15, Fedora 27, Debian 10 and Ubuntu 18.04 are recent enough (be surethe packagelibopengl0 is installed on Debian/Ubuntu)
    • Supports X11 and Wayland (set the environment variableQT_QPA_PLATFORM=xcb to disablenative Wayland support if it does not work on your system)
    • The archive is signed with the GPG keyB9E36A7275FC61B464B67907E06FE8F53CDC6A4C for manual verification.
    • The executable is signed in addition using ECDSA for verification by the updater. The public key can be foundin the source code and verificationis possible withstsigtool or OpenSSL.
  • a Flatpak is hosted onFlathub
    • Read theREADME of the Flatpak forcaveats and workarounds
    • File any Flatpak-specific issues onthe Flatpak repository
• Windows
  • for binaries checkout therelease section on GitHub
    • Windows SmartScreen will likely block the execution (you'll get a window saying "Windows protected your PC");right click on the executable, select properties and tick the checkbox to allow the execution
    • Antivirus software oftenwrongly considers the executable harmful. This is a known problem. Please don't createissues about it.
    • The Qt 6 based version is stable and preferable but only supports Windows 10 version 1809 and newer.
    • The Qt 5 based version should still work on older versions down to Windows 7 although this is not regularly checked.
      • On Windows 7 the bundled Go/Syncthing will nevertheless be too new; use a version of Go/Syncthing that isolderthan 1.21/1.27.0 instead.
    • The Universal CRT needs to beinstalled.
    • The archive is signed with the GPG keyB9E36A7275FC61B464B67907E06FE8F53CDC6A4C for manual verification.
    • The executable is signed in addition using ECDSA for verification by the updater. The public key can be foundin the source code and verificationis possible withstsigtool or OpenSSL.
  • or, using Winget, typewinget install Martchus.syncthingtray in a Command Prompt window.
  • or, usingScoop, typescoop bucket add extras & scoop install extras/syncthingtray.
  • or, via thisChocolatey package, typechoco install syncthingtray.
  • for mingw-w64 PKGBUILDs checkoutmy GitHub repository
• FreeBSD
  • the package syncthingtray is available fromFreeBSD Ports
• Mac OS X/macOS
  • the package syncthingtray is available fromMacPorts

There is separatedocumentation on these topics.

Copyright © 2016-2025 Marius Kittler

All code - unless stated otherwise in a comment on top of the file - is licensed underGPL-2-or-later. This doesnot applyto code contained in Git repositories included as Git submodule (which contain their own README and licensing information).

Syncthing Tray contains icons from various sources:

• Some icons are taken fromFork Awesome (seetheir license).These are provided viaqtforkawesome.
• The Syncthing icons are taken from theSyncthing project.
• The icons onthe website are fromMaterial Design Icons.
• All other icons found in this repository are taken from theKDE/Breeze project.

None of these icons have been (intentionally) modified so no copyright for modifications is asserted.

Some of the code is based on code from other open source projects:

• Code intray/gui/quick/quickicon.cpp and the corresponding header file originates fromKirigami. The comments at the beginning of those files state the originalauthors/contributors.
• Parts oftray/android/src/io/github/martchus/syncthingtray/Util.java are based oncom.nutomic.syncthingandroid.util.
• The icon filesic_stat_notify* undertray/android/res andtray/resources are taken fromsyncthing-android.
• The code intray/android/src/io/github/martchus/syncthingtray/DocumentsProvider.java is based onTermuxDocumentsProvider.java from Termux.
• Many of the descriptions used in the Qt Quick GUI are taken fromSyncthingandits documentation.
• Theuncamel function used in the Qt Quick GUI is taken fromSyncthing.

The original code has been modified. Copyright as mentioned in the previous section applies to modifications.