BitTorrent Sync (btsync) Desktop GUI Packaging and GUI project for delivering and deploying BitTorrent Sync (aka btsync or syncapp) on Debian derived (Ubuntu, Linux Mint, Raspbian, etc.) Linux workstations and servers

BitTorrent Sync Desktop GUI Package

BitTorrent® Sync is an excellent product, but as Linux user, you will miss the easy installation and integrated GUI provided to Windows and Mac OSX users. But now the dark age is over! Here comes the solution:

Figure 1: The indicator part
Figure 2: Adding a shared folder
Figure 3: Connect mobile device
Figure 4: Manage folder preferences
Figure 5: Manage application preferences
Figure 6: Show connected devices status

BitTorrent Sync GUI for Linux (btsync-gui) is the missing link for all Linux desktop users that aims to provide the same user experience as the original Windows or Mac OSX versions.

If you are using Arch Linux, Debian, Ubuntu, Linux Mint or any other Debian derived distribution, you will also enjoy the easy to use installation packages.


Installation on Debian and Derivates (Ubuntu, Mint, Raspian, etc)

The most easy and fast way to install the repository is to paste that at a terminal prompt:

sh -c "$(curl -fsSL"

The script explains what it will do and then pauses before it does it asking for your permission. If you encounter any problems or prefer to do it manually, please look here.

Now update the package index and install btsync-gui by pasting that at a terminal prompt

`which sudo` apt-get update
`which sudo` apt-get install btsync-gui

On some systems the AppIndicator library is not available or maybe you do not want to use it. In this case, you may install the GTK only version of the BitTorrent Sync GUI instead:

`which sudo` apt-get update
`which sudo` apt-get install btsync-gui-gtk

Please keep in mind, that this will work only on GTK based desktops. If you install it on other desktops like Unity, btsync-gui will start but you will see nothing and you have no control over the application! Install btsync-gui-gtk only if you know exactly what you are doing!!! If this happened, you can fix it by installing btsync-gui and rebooting your system.

After the successful installation, you have to initially start BitTorrent Sync. You have various possibilities to do this:

  • Log out and log in again. Since BitTorrent Sync GUI is registered in the autostart group, it will start as soon as you log in.
  • Select BitTorrent Sync from the menu or the default application launcher of your desktop.

Installation on Arch Linux

Arch Linux users will find a btsync-gui package in the AUR The package is maintained by Martin Wimpress (@flexiondotorg) and can be installed from the AUR using your favourite package manager. e.g.: if you are using yaourt:

sudo yaourt -S btsync-gui

Upgrading from btsync-user

btsync-gui is a drop-in replacement for btsync-user. By installing btsync-gui (or btsync-gui-gtk), your existing installation of btsync-user will be automatically replaced by btsync-gui without losing any data.

Usage Notes

The BitTorrent Sync GUI aims to be a clone of the original BitTorrent Sync application on Windows and Mac OSX and to replace on long term the legacy package btsync-user.

If launched without any options, the GUI starts a local BitTorrent Sync agent in the context of the user and connects to it (standalone mode). The GUI is divided into two main sections:

  • The status indicator is the central access point to BitTorrent Sync and shows information about the current status via its icon. The context menu allows to perform some operations and to open the application window.
  • The application window allows to manage the shared folders, view the connected peers, manage the standard and advanced preferences and connect mobile devices via QR-codes with the connection information.

The GUI provides two modes of operation:

  • Standalone Mode: This is the default mode. When the GUI starts, an underlaying BitTorrent Sync agent is started too providing an overall experience similar to the GUI applications on Windows or Mac OSX.
  • Client Mode: The GUI can be started from the command line with parameters specifying a connection to a remote BitTorrent Sync agent. In this case, the GUI does not start a local BitTorrent Sync agent, but connects to an already running agent at a remote location. This will work only, if the remote agent has activated API access by specifying a valid API key in the configuration file.

The behaviour of the GUI can be influenced by specifying various options on the command line. There is also a way to make some options persistent across restarts making it superfluous to specify the options each time you start the GUI. You can get detailed help about the command line options by invoking the man page:

man btsync-gui

Here you find an overview of the available options:

usage: btsync-gui [-h] [--log {CRITICAL,ERROR,WARNING,INFO,DEBUG}]
                  [--host HOST] [--port PORT] [--username USERNAME]
                  [--password PASSWORD] [--bindui BINDUI] [--webui]
                  [--savedefaults] [--cleardefaults]

optional arguments:
  -h, --help            show this help message and exit
                        Sets the logging level. By default the logging level
                        is WARNING
  --host HOST           Hostname for the connection to BitTorrent Sync. If not
                        specified, a local BitTorrent Sync agent will be
  --port PORT           Optional port number for the connection to BitTorrent
                        Sync. If not specified, port 8888 is taken for a
                        connection to a remote BitTorrent Sync agent or (8999
                        + uid) is taken when creating a locally lauched agent.
                        This option can be made persistent for local agents
                        with --savedefaults
  --username USERNAME   Optional user name for connecting to a remote
                        BitTorrent Sync agent or username to use when creating
                        a locally launched agent. This option can be made
                        persistent for local agents with --savedefaults
  --password PASSWORD   Optional password for connecting to a remote
                        BitTorrent Sync agent or password to use when creating
                        a locally launched agent. This option can be made
                        persistent for local agents with --savedefaults
  --bindui BINDUI       Optional bind address for the Web UI of a locally
                        created BitTorrent Sync agent. By default the agent
                        binds to If you want the Web UI of the
                        agent to be reachable by other computers, specify one
                        of the available IP addresses of this computer or
                        "all" to bind to all available adapters. This option
                        can be made persistent for local agents with
  --webui               Include the Web UI in the menu. This option can be
                        made persistent with --savedefaults
  --savedefaults        If specified, the optionally supplied credentials,
                        bind address and port will be stored as default in the
                        application preferences and used when launching a
                        local BitTorrent Sync agent.
  --cleardefaults       If specified, all internally stored credentials, bind
                        address and port information will be cleared from the
                        application preferences.

The usage of the command line options will be explained by some examples below.

Standalone Mode

By default there is no way to access the Web UI provided by the BitTorrent Sync agent, since the agent itself defines at each start random credentials to protect the system. If you still want to access the Web UI, you can activate an extended menu option by specifying --webui on the command line. You will then have an additional menu item, that invokes a browser and connects you to the Web UI.

If you want to make this setting persistent, you can invoke the following command from the console:

btsync-gui --webui --savedefaults

From now you will not need to specify it again at each start.

Sometimes it may happen, that you want to access your running BitTorrent Sync agent from another computer via the Web UI or a btsync-gui in Client Mode. By default this is not possible, because of two reasons:

  • The BitTorrent Sync agent binds the administration interface only to the loopback adapter making it possible to connect only from the same machine (This is a security feature).
  • The BitTorrent Sync agent is started at every time with randomly generated credentials. Without knowing them, it is impossible to access the administration interface of the agent (This is also a security feature).

For users that want to access their system from another computer, there is still a possibility to configure the GUI in a way that makes the agent accessible also from other computers. In order to do so, the following parameters must be changed:

  • The BitTorrent Sync agent must bind its administrative interface to all adapters of the system or an adapter reachable from outside.
  • The BitTorrent Sync agent must bind its administrative interface to a well-known port. By default the port is the sum of 8999 and the uid of the user.
  • The credentials must be set to something known.

The GUI can be launched in such a mode, by specifying the following parameters:

btsync-gui --bindui --port 10888 --username Leopoldo --password SuperSecret

This example configures the BitTorrent Sync agent to bind on all interfaces on port 10888 and to be accessible with the user name "Leopoldo" and the password "SuperSecret".

Also these settings can be made persistent by adding the option --savedefaults

WARNING: as every comfort function, you pay the comfort by lowering the security. Remember: the product of comfort and security is a constant. You cannot increase both.

Client Mode

In client mode, the GUI can be used to access a remotely running BitTorrent Sync agent. The only prerequisites are that the remote BitTorrent Sync agent is reachable from your computer, you know the credentials and the API access is enabled on the remote agent. You can also use the GUI to connect to another machine where a BitTorrent Sync GUI is running in standalone mode, if you have configured access possibilities like shown in the example above.

The connection to a remote BitTorrent Sync agent is done by entering the following command:

btsync-gui --host --port 8888 --username Leopoldo --password SuperSecret 

If you are able to access the Web UI of a remote BitTorrent Sync system, you should know everything you need to also launch successfully the GUI.

Since the connection to remote systems is slower, you will notice the following limitations:

  • The refresh rate is slower. It adapts dynamically to the overall performance.
  • During the status refreshes, the GUI may be a bit unresponsive.
  • There are no local file system checks, when you add a new folder. You must be sure, that you enter a valid path on the remote machine.
  • Some features are disabled (Pause/resume, Enable/Disable Debug) since they are not feasible on remote systems.


The GUI package is available for the same architectures as released by BitTorrent Inc.:

  • i386 - Intel/AMD 32 Bit
  • amd64 - Intel/AMD 64 Bit
  • armel - ARM EABI
  • armhf - ARM hard float
  • powerpc - PowerPC

The GUI packages have been tested on the following distributions:

  • Debian Wheezy with Gnome Desktop
  • Ubuntu Raring 13.04 with Unity Desktop
  • Linux Mint Petra with Cinnamon Desktop

Users have reported successful installations on:

  • Xubuntu Saucy 13.10 with OpenBox+Tint2
  • Debian Jessie with KDE
  • Ubuntu Trusty 14.04 with Cinnamon, MATE and OpenBox
  • Arch Linux with MATE

The GUI package has also been released for other Linux distributions:

  • Arch Linux: Packages can be found in the AUR

  Maintainers for other Linux distributions beeing able to write a suitable packaging for their favourite distribution:

  • Centos/RHEL (rpm)
  • Fedora (rpm)
  • SLES (rpm)
  • Gentoo

Now it's up to you to test it and give me lots of feedback in order to extend this list. Any related feedback is highly appreciated.

Bug Reports, Contribution and Sources

If you want to contribute to the development of the packages or if you are curious how this all works, you may find the current sources, the deployment scripts and packaging on GitHub (

If you want to contribute to the localisation by translating changed strings or by adding support for your favourite language, you may join the localisation team on

If you have experienced a reproducible issue that is related to the gui or the packaging and not to BitTorrent Sync itself you are strongly encouraged to open an issue on the project's GitHub Page. Issues related to the native functionality of BitTorrent Sync should instead be discussed by creating a new topic or partecipating to an already existing topic in the BitTorrent Sync Forum.

This page was last updated on May 18, 2014, 17:46:57