syncthing-faq - Frequently Asked Questions

Author

       The Syncthing Authors

Copyright

       2014-2019, The Syncthing Authors

v1.29.3                                           Mar 19, 2025                                  SYNCTHING-FAQ(7)

General

WhatisSyncthing?
Syncthing is an application that lets you synchronize your files across multiple devices. This means the
creation, modification or deletion of files on one machine will automatically be replicated to your other
devices. We believe your data is your data alone and you deserve to choose where it is stored. Therefore
Syncthing does not upload your data to the cloud but exchanges your data across your machines as soon as
they are online at the same time.

Isit“syncthing”,“Syncthing”or“SyncThing”?
It’s Syncthing, although the command and source repository is spelled syncthing so it may be referred to
in that way as well. It’s definitely not SyncThing, even though the abbreviation st is used in some
circumstances and file names.

Whatthingsaresynced?
The following things are always synchronized:

• File contents

• File modification times

The following may be synchronized or not, depending:

• File permissions (when supported by file system; on Windows only the read only bit is synchronized)

• Symbolic links (synced, except on Windows, but never followed)

• File or directory owners and groups (when enabled)

• Extended attributes (when enabled)

• POSIX or NFS ACLs (as part of extended attributes)

The following are not synchronized;

• Directory modification times (not preserved)

• Hard links (followed, not preserved)

• Windows junctions (synced as ordinary directories; require enabling in theconfiguration on a
per-folder basis)

• Resource forks (not preserved)

• Windows ACLs (not preserved)

• Devices, FIFOs, and other specials (ignored)

• Sparse file sparseness (will become sparse, when supported by the OS & filesystem)

• Syncthing internal files and folders (e.g. .stfolder, .stignore, .stversions, temporaryfiles, etc.)

Issynchronizationfast?
Syncthing segments files into pieces, called blocks, to transfer data from one device to another.
Therefore, multiple devices can share the synchronization load, in a similar way to the torrent protocol.
The more devices you have online, the faster an additional device will receive the data because small
blocks will be fetched from all devices in parallel.

Syncthing handles renaming files and updating their metadata in an efficient manner. This means that
renaming a file will not cause a retransmission of that file. Additionally, appending data to existing
files should be handled efficiently as well.

Temporaryfiles are used to store partial data downloaded from other devices. They are automatically
removed whenever a file transfer has been completed or after the configured amount of time which is set
in the configuration file (24 hours by default).

HowdoesSyncthingdifferfromBitTorrent/ResilioSync?
The two are different and not related. Syncthing and BitTorrent/Resilio Sync accomplish some of the same
things, namely syncing files between two or more computers.

BitTorrent Sync, now called Resilio Sync, is a proprietary peer-to-peer file synchronization tool
available for Windows, Mac, Linux, Android, iOS, Windows Phone, Amazon Kindle Fire and BSD. [1] Syncthing
is an open source file synchronization tool.

Syncthing uses an open and documented protocol, and likewise the security mechanisms in use are well
defined and visible in the source code. Resilio Sync uses an undocumented, closed protocol with unknown
security properties.

[1] https://en.wikipedia.org/wiki/Resilio_SyncIsthereaniOSclient?
There are no plans by the current Syncthing team to officially support iOS in the foreseeable future.

iOS has significant restrictions on background processing that make it very hard to run Syncthing
reliably and integrate it into the system.

However, there is an open source app for iOS, incorporating Syncthing, that attempts to work within these
limitations. It provides a native UI and features for selective synchronization as well as on-demand
access to files. Most Syncthing features are available, but the native UI is simplified compared to the
official client. [2]

There is also a commercial packaging of Syncthing. It provides access to all Syncthing functionalities
through the original UI. [3]

[2] https://github.com/pixelspark/sushitrain

[3] https://www.mobiussync.comShouldIkeepmydeviceIDssecret?
No. The IDs are not sensitive. Given a device ID it’s possible to find the IP address for that device, if
global discovery is enabled on it. Knowing the device ID doesn’t help you actually establish a connection
to that device or get a list of files, etc.

For a connection to be established, both devices need to know about the other’s device ID. It’s not
possible (in practice) to forge a device ID. (To forge a device ID you need to create a TLS certificate
with that specific SHA-256 hash. If you can do that, you can spoof any TLS certificate. The world is
your oyster!)

SEEALSO:UnderstandingDeviceIDs

Name

       syncthing-faq - Frequently Asked Questions

       • General

         • WhatisSyncthing?

         • Isit“syncthing”,“Syncthing”or“SyncThing”?

         • Whatthingsaresynced?

         • Issynchronizationfast?

         • HowdoesSyncthingdifferfromBitTorrent/ResilioSync?

         • IsthereaniOSclient?

         • ShouldIkeepmydeviceIDssecret?

       • Troubleshooting

         • WherearetheSyncthinglogs?

         • Whyisthesyncsoslow?

         • WhydoesitusesomuchCPU?

         • WhyisthesetupmorecomplicatedthanBitTorrent/ResilioSync?

         • WhydoIget“Hostcheckerror”intheGUI/API?

         • MySyncthingdatabaseiscorrupt

         • WhydoIseeSyncthingtwiceintaskmanager?

         • HowcanIviewthehistoryofchanges?

         • Doestheauditlogcontaineverychange?

         • WhydoesSyncthingconnecttothisunknown/suspiciousaddress?

         • Iamseeingtheerrormessage“foldermarkermissing”.WhatdoIdo?

       • Usage

         • Whatifthereisaconflict?

         • HowdoIserveafolderfromareadonlyfilesystem?

         • Ireallyhatethe.stfolderdirectory,canIremoveit?

         • AmIabletonestsharedfoldersinSyncthing?

         • HowdoIrename/moveasyncedfolder?

         • HowdoIconfiguremultipleusersonasinglemachine?

         • DoesSyncthingsupportsyncingbetweenfoldersonthesamesystem?

         • WhenIdohavetwodistinctSyncthing-managedfoldersontwohosts,howdoesSyncthinghandlemovingfilesbetweenthem?

         • CanIhelpinitialsyncbycopyingfilesmanually?

         • IsSyncthingmyidealbackupapplication?

         • HowcanIexcludefileswithbrackets([])inthename?

         • HowdoIaccessthewebGUIfromanothercomputer?

         • Idon’tliketheGUIorthetheme.Canitbechanged?

         • HowdoIupgradeSyncthing?

         • WheredoIfindthelatestrelease?

         • HowdoIrunSyncthingasadaemonprocessonLinux?

         • HowdoIincreasetheinotifylimittogetmyfilesystemwatchertowork?

         • HowdoIresettheGUIpassword?

Troubleshooting

WherearetheSyncthinglogs?
Syncthing logs to stdout by default. On Windows Syncthing by default also creates syncthing.log in
Syncthing’s home directory (run syncthing--paths to see where that is). The command line option
--logfile can be used to specify a user-defined logfile. If you only have access to a running instance’s
GUI, check under the Actions - About menu item to see the used paths.

If you’re running a process manager like systemd, check there. If you’re using a GUI wrapper integration,
it may keep the logs for you.

Whyisthesyncsoslow?
When troubleshooting a slow sync, there are a number of things to check.

First of all, verify that you are not connected via a relay. In the “Remote Devices” list on the right
side of the GUI, double check that the Connection Type does not start with “Relay”.

Here is an example of a device connected via a relay: [image]

If you are connected via a relay, this is because a direct connection could not be established. Double
check and follow the suggestions in FirewallSetup to enable direct connections.

Second, if one of the devices is a very low powered machine (a Raspberry Pi, or a phone, or a NAS, or
similar) you are likely constrained by the CPU on that device. See the next question for reasons
Syncthing likes a faster CPU.

Third, verify that the network connection is OK. Tools such as iperf or just an Internet speed test can
be used to verify the performance here.

WhydoesitusesomuchCPU?
1. When new or changed files are detected, or Syncthing starts for the first time, your files are hashed
using SHA-256.

2. Data that is sent over the network is compressed (optionally) and encrypted (always). When receiving
data it must be decrypted and then (if compressed) decompressed.

3. There is a certain amount of housekeeping that must be done to track the current and available
versions of each file in the index database.

4. By default Syncthing uses periodic scanning every hour when watching for changes or every minute if
that’s disabled to detect file changes. This means checking every file’s modification time and
comparing it to the database. This can cause spikes of CPU usage for large folders.

Hashing, compression and encryption cost CPU time. Also, using the GUI causes a certain amount of extra
CPU usage to calculate the summary data it presents. Note however that once things are insync CPU usage
should be negligible.

To minimize the impact of this, Syncthing attempts to lowertheprocesspriority when starting up.

To further limit the amount of CPU used when syncing and scanning, set the environment variable
GOMAXPROCS to the maximum number of CPU cores Syncthing should use at any given moment. For example,
GOMAXPROCS=2 on a machine with four cores will limit Syncthing to no more than half the system’s CPU
power.

WhyisthesetupmorecomplicatedthanBitTorrent/ResilioSync?
Security over convenience. In Syncthing you have to setup both sides to connect two devices. An attacker
can’t do much with a stolen device ID, because you have to add the device on the other side too. You have
better control where your files are transferred.

This is an area that we are working to improve in the long term.

WhydoIget“Hostcheckerror”intheGUI/API?
Since version 0.14.6 Syncthing does an extra security check when the GUI/API is bound to localhost -
namely that the browser is talking to localhost. This protects against most forms of DNSrebindingattack <https://en.wikipedia.org/wiki/DNS_rebinding> against the GUI.

To pass this test, ensure that you are accessing the GUI using an URL that begins with http://localhost,
http://127.0.0.1 or http://[::1]. HTTPS is fine too, of course.

If you are using a proxy in front of Syncthing you may need to disable this check, after ensuring that
the proxy provides sufficient authentication to protect against unauthorized access. Either:

• Make sure the proxy sets a Host header containing localhost, or

• Set gui.insecureSkipHostcheck in the advanced settings, or

• Bind the GUI/API to a non-localhost listen port.

In all cases, username/password authentication and HTTPS should be used.

MySyncthingdatabaseiscorrupt
This is almost always a result of bad RAM, storage device or other hardware. When the index database is
found to be corrupt Syncthing cannot operate and will note this in the logs and exit. To overcome this
delete the databasefolder inside Syncthing’s data directory and re-start Syncthing. It will then need to
perform a full re-hashing of all shared folders. You should check your system in case the underlying
cause is indeed faulty hardware which may put the system at risk of further data loss.

WhydoIseeSyncthingtwiceintaskmanager?
One process manages the other, to capture logs and manage restarts. This makes it easier to handle
upgrades from within Syncthing itself, and also ensures that we get a nice log file to help us narrow
down the cause for crashes and other bugs.

HowcanIviewthehistoryofchanges?
The web GUI contains a RecentChanges button under the device list which displays changes since the last
(re)start of Syncthing. With the --audit option you can enable a persistent, detailed log of changes and
most activities, which contains a JSON-formatted sequence of events in the
~/.local/state/syncthing/audit-_date_-_time_.log file.

Doestheauditlogcontaineverychange?
The audit log (and the RecentChanges window) sees the changes that your Syncthing sees. When Syncthing
is continuously connected it usually sees every change happening immediately and thus knows which node
initiated the change. When topology gets complex or when your node reconnects after some time offline,
Syncthing synchronises with its neighbours: It gets the latest synchronised state from the neighbour,
which is the result of all the changes between the last known state (before disconnect or network delay)
and the current state at the neighbour, and if there were updates, deletes, creates, conflicts, which
were overlapping we only see the latestchange for a given file or directory (and the node where that
latest change occurred). When we connect to multiple neighbours Syncthing decides which neighbour has the
latest state, or if the states conflict it initiates the conflict resolution procedure, which in the end
results in a consistent up-to-date state with all the neighbours.

WhydoesSyncthingconnecttothisunknown/suspiciousaddress?
If you see outgoing connections to odd and unexpected addresses these are most likely connections to
relayservers. Relay servers are run by volunteers all over the world. They usually listen on ports 443
or 22067, though this is controlled by the user running it. You can compare the address you are concerned
about with thecurrentlistofactiverelays <https://relays.syncthing.net>. Relays do not and can not
see the data transmitted via them.

Iamseeingtheerrormessage“foldermarkermissing”.WhatdoIdo?
Syncthing uses a specific marker usually called .stfolder to determine whether a folder is healthy. This
is a safety check to ensure that your folder is properly readable and present on disk. For example, if
you remove a USB drive from your computer or unmount a filesystem, then syncthing must know whether you
have really deleted all of your files. Therefore, syncthing always checks that the .stfolder is present.

When this error appears, syncthing assumes that the folder has encountered some type of error and will
stop syncing it until the .stfolder reappears. Once that happens, all changes made to the folder locally
will be synced (i.e. missing files will be considered deletions).

• If you get this error message, check the folder in question on your storage. If you have unmounted the
folder (or a parent of it), you must remount it for syncthing to resume syncing this folder.

• If you have moved the folder, you must either move it back to its original location, or remove the
folder from within the syncthing UI and re-add it at its new location.

• If the folder is present on disk, with all of its children files and directories, but the .stfolder is
still missing:

It is possible that a file cleaning software has removed the .stfolder. Some software removes empty
folders, and the .stfolder is often empty. This happens particularly often on Android. To remediate,
recreate the .stfolder and add a dummy file in it, or add an exception to your cleaning software.

If you are still unsure what has happened, you can remove the folder from within the syncthing UI and
re-add it at the same location. This causes syncthing to attempt an automatic re-creation of the
.stfolder. Next, it will also reset the database state of this folder. It will be considered a “new”
folder, meaning that its files will be merged with files from remote devices.

Also see the markerFAQ for more information about the folder marker.

Usage

Whatifthereisaconflict?SEEALSO:ConflictingChangesHowdoIserveafolderfromareadonlyfilesystem?
Syncthing requires a “folder marker” to indicate that the folder is present and healthy. By default this
is a directory called .stfolder that is created by Syncthing when the folder is added. If this folder
can’t be created (you are serving files from a CD or something) you can instead set the advanced config
MarkerName to the name of some file or folder that you know will always exist in the folder.

Ireallyhatethe.stfolderdirectory,canIremoveit?
See the previous question.

AmIabletonestsharedfoldersinSyncthing?
Sharing a folder that is within an already shared folder is possible, but it has its caveats. What you
must absolutely avoid are circular shares. This is just one example, there may be other undesired
effects. Nesting shared folders is not supported, recommended or coded for, but it can be done
successfully when you know what you’re doing - you have been warned.

HowdoIrename/moveasyncedfolder?
Syncthing doesn’t have a direct way to do this, as it’s potentially dangerous to do so if you’re not
careful - it may result in data loss if something goes wrong during the move and is synchronized to your
other devices.

The easy way to rename or move a synced folder on the local system is to remove the folder in the
Syncthing UI, move it on disk, then re-add it using the new path.

It’s important to do this when the folder is already in sync between your devices, as it is otherwise
unpredictable which changes will “win” after the move. Changes made on other devices may be overwritten,
or changes made locally may be overwritten by those on other devices.

An alternative way is to shut down Syncthing, move the folder on disk (including the .stfolder marker),
edit the path directly in config.xml in the configuration folder (see SyncthingConfiguration) and then
start Syncthing again.

HowdoIconfiguremultipleusersonasinglemachine?
Each user should run their own Syncthing instance. Be aware that you might need to configure listening
ports such that they do not overlap (see SyncthingConfiguration).

DoesSyncthingsupportsyncingbetweenfoldersonthesamesystem?
No. Syncthing is not designed to sync locally and the overhead involved in doing so using Syncthing’s
method would be wasteful. There are better programs to achieve this such as rsync
<https://rsync.samba.org/> or Unison <https://www.cis.upenn.edu/~bcpierce/unison>.

WhenIdohavetwodistinctSyncthing-managedfoldersontwohosts,howdoesSyncthinghandlemovingfilesbetweenthem?
Syncthing does not specially handle this case, and most files will most likely get re-downloaded.

In detail, the behavior depends on the scan order. If you have folders A and B, and move files from A to
B, if A gets scanned first, it will announce the removal of the files to others who will then remove the
files. As you rescan B, B will announce the addition of new files, and other peers will have nowhere to
get them from apart from re-downloading them.

If B gets rescanned first, B will announce additions first, and remote peers will then reconstruct the
files (not rename, more like copying block by block) from A, and then as A gets rescanned, it will remove
the files from A.

A workaround would be to copy first from A to B, rescan B, wait for B to copy the files on the remote
side, and then delete from A.

CanIhelpinitialsyncbycopyingfilesmanually?
If you have a large folder that you want to keep in sync over a not-so-fast network, and you have the
possibility to move all files to the remote device in a faster manner, here is a procedure to follow:

• Create the folder on the local device, but don’t share it with the remote device yet.

• Copy the files from the local device to the remote device using regular file copy. If this takes a long
time (perhaps requiring travelling there physically), it may be a good idea to make sure that the files
on the local device are not updated while you are doing this.

• Create the folder on the remote device, and copy the Folder ID from the folder on the local device, as
we want the folders to be considered the same. Then wait until scanning the folder is done.

• Now share the folder with the other device, on both sides. Syncthing will exchange file information,
updating the database, but existing files will not be transferred. This may still take a while
initially, be patient and wait until it settled.

IsSyncthingmyidealbackupapplication?
No. Syncthing is not a great backup application because all changes to your files (modifications,
deletions, etc.) will be propagated to all your devices. You can enable versioning, but we encourage you
to use other tools to keep your data safe from your (or our) mistakes.

HowcanIexcludefileswithbrackets([])inthename?
The patterns in .stignore are glob patterns, where brackets are used to denote character ranges. That is,
the pattern q[abc]x will match the files qax, qbx and qcx.

To match an actual file calledq[abc]x the pattern needs to “escape” the brackets, like so: q\[abc\]x.

On Windows, escaping special characters is not supported as the \ character is used as a path separator.

HowdoIaccessthewebGUIfromanothercomputer?
The default listening address is 127.0.0.1:8384, so you can only access the GUI from the same machine.
This is for security reasons. To access it from another computer, change the GUIlistenaddress option
in the web GUI from 127.0.0.1:8384 to 0.0.0.0:8384, or change the config.xml:

Then the GUI is accessible from everywhere. There is no filtering based on e.g. source address (use a
firewall for that). You should set a password and enable HTTPS with this configuration. You can do this
from inside the GUI.

If both your computers are Unix-like (Linux, Mac, etc.) you can also leave the GUI settings at default
and use an SSH port forward to access it. For example,

$ ssh -L 9090:127.0.0.1:8384 user@othercomputer.example.com

will log you into othercomputer.example.com, and present the remote Syncthing GUI on ‐
http://localhost:9090 on your local computer.

If you only want to access the remote GUI and don’t want the terminal session, use this example:

$ ssh -N -L 9090:127.0.0.1:8384 user@othercomputer.example.com

If only your remote computer is Unix-like, you can still access it with SSH from Windows. Under Windows
10 or later you can use the same ssh command if you installtheOpenSSHClient
<https://learn.microsoft.com/windows-server/administration/openssh/openssh_install_firstuse>.

Idon’tliketheGUIorthetheme.Canitbechanged?
You can change the theme in the settings. Syncthing ships with other themes than the default.

If you want a custom theme or a completely different GUI, you can add your own. By default, Syncthing
will look for a directory gui inside the Syncthing home folder. To change the directory to look for
themes, you need to set the STGUIASSETS environment variable. To get the concrete directory, run
syncthing with the --paths parameter. It will print all the relevant paths, including the “GUI override
directory”.

To add e.g. a red theme, you can create the file red/assets/css/theme.css inside the GUI override
directory to override the default CSS styles.

To create a whole new GUI, you should checkout the files at ‐
https://github.com/syncthing/syncthing/tree/main/gui/default to get an idea how to do that.

HowdoIupgradeSyncthing?
If you use a package manager such as Debian’s apt-get, you should upgrade using the package manager. If
you use the binary packages linked from Syncthing.net, you can use Syncthing’s built-in automatic upgrade
functionality.

• If automatic upgrades is enabled (which is the default), Syncthing will upgrade itself automatically
within 24 hours of a new release.

• The upgrade button appears in the web GUI when a new version has been released. Pressing it will
perform an upgrade.

• To force an upgrade from the command line, run syncthing--upgrade.

Note that your system should have CA certificates installed which allows a secure connection to GitHub
(e.g. FreeBSD requires sudopkginstallca_root_nss). If curl or wget works with normal HTTPS sites, then
so should Syncthing.

WheredoIfindthelatestrelease?
We release new versions through GitHub. The latest release is always found onthereleasepage
<https://github.com/syncthing/syncthing/releases/latest>. Unfortunately GitHub does not provide a single
URL to automatically download the latest version. We suggest to use the GitHubAPI
<https://api.github.com/repos/syncthing/syncthing/releases/latest> and parsing the JSON response.

HowdoIrunSyncthingasadaemonprocessonLinux?
If you’re using systemd, runit, or upstart, we ship exampleconfigurations
<https://github.com/syncthing/syncthing/tree/main/etc>.

If however you’re not using one of these tools, you have a couple of options. If your system has a tool
called start-stop-daemon installed (that’s the name of the command, not the package), look into the local
documentation for that, it will almost certainly cover 100% of what you want to do. If you don’t have
start-stop-daemon, there are a bunch of other software packages you could use to do this. The most well
known is called daemontools, and can be found in the standard package repositories for almost every
modern Linux distribution. Other popular tools with similar functionality include S6 and the
aforementioned runit.

HowdoIincreasetheinotifylimittogetmyfilesystemwatchertowork?
You are probably reading this because you encountered the following error with the filesystem watcher on
linux:
Failed to start filesystem watcher for folder yourLabel (yourID): failed to setup inotify handler.
Please increase inotify limits, see https://docs.syncthing.net/users/faq.html#inotify-limits

Linux typically restricts the number of watches per user (usually 8192). If you have many directories,
you will need to adjust that number.

On many Linux distributions you can run the following to fix it:

echo "fs.inotify.max_user_watches=204800" | sudo tee -a /etc/sysctl.conf

On Arch Linux and potentially others it is preferred to write this line into a separate file, i.e. you
should run:

echo "fs.inotify.max_user_watches=204800" | sudo tee -a /etc/sysctl.d/90-override.conf

This only takes effect after a reboot. To adjust the limit immediately, run:

echo 204800 | sudo tee /proc/sys/fs/inotify/max_user_watchesHowdoIresettheGUIpassword?
If you’ve forgotten / lost the GUI password, you can reset it using the --gui-password (and possibly
--gui-user) options to the syncthinggenerate subcommand. This should be done while Syncthing is not
running.

1. Stop Syncthing: syncthingclioperationsshutdown

2. syncthinggenerate--gui-password=myNewPassword--gui-user=newUserName

3. Restart Syncthing as usual.

Alternatively,instep2, you can manually delete the <user> and <password> XML tags from the <gui> block
in file config.xml. The location of the file depends on the OS and is described in the configurationdocumentation.

For example, the two emphasized lines below would be removed from the file.

<gui enabled="true" tls="false" debugging="false">
<address>127.0.0.1:8384</address>
<user>syncguy</user>
<password>$2a$10$s9wWHOQe...Cq7GPye69</password>
<apikey>9RCKohqCAyrj5RjpyZdR2wXmQ9PyQFeN</apikey>
<theme>default</theme>
</gui>