---

title: "Local Filesystem" description: "Rclone docs for the local filesystem" versionIntroduced: "v0.91"

Local Filesystem

Local paths are specified as normal filesystem paths, e.g. /path/to/wherever, so

rclone sync --interactive /home/source /tmp/destination

Will sync /home/source to /tmp/destination.

Configuration

For consistencies sake one can also configure a remote of type local in the config file, and access the local filesystem using rclone remote paths, e.g. remote:path/to/wherever, but it is probably easier not to.

Modification times

Rclone reads and writes the modification times using an accuracy determined by the OS. Typically this is 1ns on Linux, 10 ns on Windows and 1 Second on OS X.

Filenames

Filenames should be encoded in UTF-8 on disk. This is the normal case for Windows and OS X.

There is a bit more uncertainty in the Linux world, but new distributions will have UTF-8 encoded files names. If you are using an old Linux filesystem with non UTF-8 file names (e.g. latin1) then you can use the convmv tool to convert the filesystem to UTF-8. This tool is available in most distributions' package managers.

If an invalid (non-UTF8) filename is read, the invalid characters will be replaced with a quoted representation of the invalid bytes. The name gro\xdf will be transferred as gro‛DF. rclone will emit a debug message in this case (use -v to see), e.g.

Local file system at .: Replacing invalid UTF-8 characters in "gro\xdf"

Restricted characters

With the local backend, restrictions on the characters that are usable in file or directory names depend on the operating system. To check what rclone will replace by default on your system, run rclone help flags local-encoding.

On non Windows platforms the following characters are replaced when handling file names.

When running on Windows the following characters are replaced. This list is based on the Windows file naming conventions.

File names on Windows can also not end with the following characters. These only get replaced if they are the last character in the name:

Invalid UTF-8 bytes will also be replaced, as they can't be converted to UTF-16.

Paths on Windows

On Windows there are many ways of specifying a path to a file system resource. Local paths can be absolute, like C:\path\to\wherever, or relative, like ..\wherever. Network paths in UNC format, \\server\share, are also supported. Path separator can be either \ (as in C:\path\to\wherever) or / (as in C:/path/to/wherever). Length of these paths are limited to 259 characters for files and 247 characters for directories, but there is an alternative extended-length path format increasing the limit to (approximately) 32,767 characters. This format requires absolute paths and the use of prefix \\?\, e.g. \\?\D:\some\very\long\path. For convenience rclone will automatically convert regular paths into the corresponding extended-length paths, so in most cases you do not have to worry about this (read more below). Using the same prefix \\?\ it is also possible to specify path to volumes identified by their GUID, e.g. \\?\Volume{b75e2c83-0000-0000-0000-602f00000000}\some\path.

Long paths

Rclone handles long paths automatically, by converting all paths to extended-length path format, which allows paths up to 32,767 characters.

This conversion will ensure paths are absolute and prefix them with the \\?\. This is why you will see that your paths, for instance .\files is shown as path \\?\C:\files in the output, and \\server\share as \\?\UNC\server\share.

However, in rare cases this may cause problems with buggy file system drivers like EncFS. To disable UNC conversion globally, add this to your .rclone.conf file:

[local]
nounc = true

If you want to selectively disable UNC, you can add it to a separate entry like this:

[nounc]
type = local
nounc = true

And use rclone like this:

rclone copy c:\src nounc:z:\dst

This will use UNC paths on c:\src but not on z:\dst. Of course this will cause problems if the absolute path length of a file exceeds 259 characters on z, so only use this option if you have to.

Symlinks / Junction points

Normally rclone will ignore symlinks or junction points (which behave like symlinks under Windows).

If you supply --copy-links or -L then rclone will follow the symlink and copy the pointed to file or directory. Note that this flag is incompatible with --links / -l.

This flag applies to all commands.

For example, supposing you have a directory structure like this

$ tree /tmp/a
/tmp/a
├── b -> ../b
├── expected -> ../expected
├── one
└── two
    └── three

Then you can see the difference with and without the flag like this

$ rclone ls /tmp/a
        6 one
        6 two/three

and

$ rclone -L ls /tmp/a
     4174 expected
        6 one
        6 two/three
        6 b/two
        6 b/one

--local-links, --links, -l

Normally rclone will ignore symlinks or junction points (which behave like symlinks under Windows).

If you supply this flag then rclone will copy symbolic links from the local storage, and store them as text files, with a .rclonelink suffix in the remote storage.

The text file will contain the target of the symbolic link (see example).

This flag applies to all commands.

For example, supposing you have a directory structure like this

$ tree /tmp/a
/tmp/a
├── file1 -> ./file4
└── file2 -> /home/user/file3

Copying the entire directory with '-l'

rclone copy -l /tmp/a/ remote:/tmp/a/

The remote files are created with a .rclonelink suffix

$ rclone ls remote:/tmp/a
       5 file1.rclonelink
      14 file2.rclonelink

The remote files will contain the target of the symbolic links

$ rclone cat remote:/tmp/a/file1.rclonelink
./file4

$ rclone cat remote:/tmp/a/file2.rclonelink
/home/user/file3

Copying them back with '-l'

$ rclone copy -l remote:/tmp/a/ /tmp/b/

$ tree /tmp/b
/tmp/b
├── file1 -> ./file4
└── file2 -> /home/user/file3

However, if copied back without '-l'

$ rclone copyto remote:/tmp/a/ /tmp/b/

$ tree /tmp/b
/tmp/b
├── file1.rclonelink
└── file2.rclonelink

If you want to copy a single file with -l then you must use the .rclonelink suffix.

$ rclone copy -l remote:/tmp/a/file1.rclonelink /tmp/c

$ tree /tmp/c
/tmp/c
└── file1 -> ./file4

Note that --local-links just enables this feature for the local backend. --links and -l enable the feature for all supported backends and the VFS.

Note that this flag is incompatible with -copy-links / -L.

Symlink targets and the destination

When rclone recreates a .rclonelink file as a symlink on local storage, the symlink can point anywhere - including, with an absolute path or one using ../ - to a location outside the directory you are copying into. This is normal - rclone reproduces whatever target the link had, so backups round-trip faithfully.

What rclone will not do is write through such a link. If a remote you are copying from contains both a symlink and a file or directory that would be placed inside it - for example a dir.rclonelink pointing somewhere outside the destination, alongside a dir/file.txt - rclone refuses to follow the symlink when writing dir/file.txt. The offending file is skipped with an error, the rest of the transfer continues, and the skipped file is counted in the error summary printed at the end of the run.

This protects you from a malicious or compromised remote using -l / --links to plant a symlink and then write through it to somewhere outside your destination. Ordinary symlink round-trips, and symlinks that stay inside the destination, are unaffected.

If you have intentionally pre-created a symlinked directory inside your destination and want rclone to write into the directory it points at, do not use -l / --links for that copy, or remove the symlink first.

Restricting filesystems with --one-file-system

Normally rclone will recurse through filesystems as mounted.

However if you set --one-file-system or -x this tells rclone to stay in the filesystem specified by the root and not to recurse into different file systems.

For example if you have a directory hierarchy like this

root
├── disk1     - disk1 mounted on the root
│   └── file3 - stored on disk1
├── disk2     - disk2 mounted on the root
│   └── file4 - stored on disk12
├── file1     - stored on the root disk
└── file2     - stored on the root disk

Using rclone --one-file-system copy root remote: will only copy file1 and file2. E.g.

$ rclone -q --one-file-system ls root
        0 file1
        0 file2

$ rclone -q ls root
        0 disk1/file3
        0 disk2/file4
        0 file1
        0 file2

NB Rclone (like most unix tools such as du, rsync and tar) treats a bind mount to the same device as being on the same filesystem.

NB This flag is only available on Unix based systems. On systems where it isn't supported (e.g. Windows) it will be ignored.

Advanced options

Here are the Advanced options specific to local (Local Disk).

--local-nounc

Disable UNC (long path names) conversion on Windows.

Properties:

• Config: nounc
• Env Var: RCLONE_LOCAL_NOUNC
• Type: bool
• Default: false
• Examples:
  • "true"
    • Disables long file names.

--copy-links / -L

Follow symlinks and copy the pointed to item.

Properties:

• Config: copy_links
• Env Var: RCLONE_LOCAL_COPY_LINKS
• Type: bool
• Default: false

--local-links

Translate symlinks to/from regular files with a '.rclonelink' extension for the local backend.

Properties:

• Config: links
• Env Var: RCLONE_LOCAL_LINKS
• Type: bool
• Default: false

--skip-links

Don't warn about skipped symlinks.

This flag disables warning messages on skipped symlinks or junction points, as you explicitly acknowledge that they should be skipped.

Properties:

• Config: skip_links
• Env Var: RCLONE_LOCAL_SKIP_LINKS
• Type: bool
• Default: false

--skip-specials

Don't warn about skipped pipes, sockets and device objects.

This flag disables warning messages on skipped pipes, sockets and device objects, as you explicitly acknowledge that they should be skipped.

Properties:

• Config: skip_specials
• Env Var: RCLONE_LOCAL_SKIP_SPECIALS
• Type: bool
• Default: false

--local-zero-size-links

Assume the Stat size of links is zero (and read them instead) (deprecated).

Rclone used to use the Stat size of links as the link size, but this fails in quite a few places:

• Windows
• On some virtual filesystems (such ash LucidLink)
• Android

So rclone now always reads the link.

Properties:

• Config: zero_size_links
• Env Var: RCLONE_LOCAL_ZERO_SIZE_LINKS
• Type: bool
• Default: false

--local-unicode-normalization

Apply unicode NFC normalization to paths and filenames.

This flag can be used to normalize file names into unicode NFC form that are read from the local filesystem.

Rclone does not normally touch the encoding of file names it reads from the file system.

This can be useful when using macOS as it normally provides decomposed (NFD) unicode which in some language (eg Korean) doesn't display properly on some OSes.

Note that rclone compares filenames with unicode normalization in the sync routine so this flag shouldn't normally be used.

Properties:

• Config: unicode_normalization
• Env Var: RCLONE_LOCAL_UNICODE_NORMALIZATION
• Type: bool
• Default: false

--local-no-check-updated

Don't check to see if the files change during upload.

Normally rclone checks the size and modification time of files as they are being uploaded and aborts with a message which starts "can't copy - source file is being updated" if the file changes during upload.

However on some file systems this modification time check may fail (e.g. Glusterfs #2206) so this check can be disabled with this flag.

If this flag is set, rclone will use its best efforts to transfer a file which is being updated. If the file is only having things appended to it (e.g. a log) then rclone will transfer the log file with the size it had the first time rclone saw it.

If the file is being modified throughout (not just appended to) then the transfer may fail with a hash check failure.