vagrant/website/source/docs/synced-folders/rsync.html.md

---
layout: "docs"
page_title: "RSync - Synced Folders"
sidebar_current: "syncedfolder-rsync"
description: |-
  Vagrant can use rsync as a mechanism to sync a folder to the guest machine.
  This synced folder type is useful primarily in situations where other synced
  folder mechanisms are not available, such as when NFS or VirtualBox shared
  folders are not available in the guest machine.
---

# RSync

**Synced folder type:** `rsync`

Vagrant can use [rsync](https://en.wikipedia.org/wiki/Rsync) as a mechanism
to sync a folder to the guest machine. This synced folder type is useful
primarily in situations where other synced folder mechanisms are not available,
such as when NFS or VirtualBox shared folders are not available in the guest
machine.

The rsync synced folder does a one-time one-way sync from the machine running
to the machine being started by Vagrant.

The [rsync](/docs/cli/rsync.html) and [rsync-auto](/docs/cli/rsync-auto.html)
commands can be used to force a resync and to automatically resync when
changes occur in the filesystem. Without running these commands, Vagrant
only syncs the folders on `vagrant up` or `vagrant reload`.

## Prerequisites

To use the rsync synced folder type, the machine running Vagrant must have
`rsync` (or `rsync.exe`) on the path. This executable is expected to behave
like the standard rsync tool.

On Windows, rsync installed with Cygwin or MinGW will be detected by
Vagrant and works well.

The destination machine must also have rsync installed, but Vagrant
can automatically install rsync into many operating systems. If Vagrant
is unable to automatically install rsync for your operating system,
it will tell you.

The destination folder will be created as the user initiating the connection,
this is `vagrant` by default. This user requires the appropriate permissions on
the destination folder.

## Options

The rsync synced folder type accepts the following options:

* `rsync__args` (array of strings) - A list of arguments to supply
  to `rsync`. By default this is `["--verbose", "--archive", "--delete", "-z", "--copy-links"]`.

* `rsync__auto` (boolean) - If false, then `rsync-auto` will not
  watch and automatically sync this folder. By default, this is true.

* `rsync__chown` (boolean) - If false, then the
  [`owner` and `group`](/docs/synced-folders/basic_usage.html)
  options for the synced folder are ignored and Vagrant will not execute
  a recursive `chown`. This defaults to true. This option exists because
  the `chown` causes issues for some development environments. Note that
  any `rsync__args` options for ownership **will be overridden** by
  `rsync__chown`.

* `rsync__exclude` (string or array of strings) - A list of files or directories
  to exclude from the sync. The values can be any acceptable rsync exclude
  pattern. By default, the ".vagrant/" directory is excluded. We recommend
  excluding revision control directories such as ".git/" as well.

* `rsync__rsync_path` (string) - The path on the remote host where rsync
  is and how it is executed. This is platform specific but defaults to
  "sudo rsync" for many guests.

* `rsync__verbose` (boolean) - If true, then the output from the rsync
  process will be echoed to the console. The output of rsync is subject
  to `rsync__args` of course. By default, this is false.

## Example

The following is an example of using RSync to sync a folder:

```ruby
Vagrant.configure("2") do |config|
  config.vm.synced_folder ".", "/vagrant", type: "rsync",
    rsync__exclude: ".git/"
end
```

## Rsync to a restricted folder

If required to copy to a destination where `vagrant` user does not have
permissions, use `"--rsync-path='sudo rsync'"` to run rsync with sudo on the guest

```ruby
Vagrant.configure("2") do |config|
  config.vm.synced_folder "bin", "/usr/local/bin", type: "rsync",
    rsync__exclude: ".git/",
    rsync__args: ["--verbose", "--rsync-path='sudo rsync'", "--archive", "--delete", "-z"]
end
```