A new platform for documentation and tutorials is launching soon.
We are migrating Vagrant documentation into HashiCorp Developer, our new developer experience.
Synced folders are configured within your Vagrantfile using the
config.vm.synced_folder method. Usage of the configuration directive
is very simple:
Vagrant.configure("2") do |config| # other config here config.vm.synced_folder "src/", "/srv/website" end
The first parameter is a path to a directory on the host machine. If the path is relative, it is relative to the project root. The second parameter must be an absolute path of where to share the folder within the guest machine. This folder will be created (recursively, if it must) if it does not exist. By default, Vagrant mounts the synced folders with the owner/group set to the SSH user and any parent folders set to root.
You may also specify additional optional parameters when configuring synced folders. These options are listed below. More detailed examples of using some of these options are shown below this section, note the owner/group example supplies two additional options separated by commas.
In addition to these options, the specific synced folder type might allow more options. See the documentation for your specific synced folder type for more details. The built-in synced folder types are documented in other pages available in the navigation for these docs.
create(boolean) - If true, the host path will be created if it does not exist. Defaults to false.
disabled(boolean) - If true, this synced folder will be disabled and will not be setup. This can be used to disable a previously defined synced folder or to conditionally disable a definition based on some external factor.
group(string) - The group that will own the synced folder. By default this will be the SSH user. Some synced folder types do not support modifying the group.
mount_options(array) - A list of additional mount options to pass to the
owner(string) - The user who should be the owner of this synced folder. By default this will be the SSH user. Some synced folder types do not support modifying the owner.
type(string) - The type of synced folder. If this is not specified, Vagrant will automatically choose the best synced folder option for your environment. Otherwise, you can specify a specific type such as "nfs".
id(string) - The name for the mount point of this synced folder in the guest machine. This shows up when you run
mountin the guest machine.
Synced folders are automatically setup during
vagrant up and
Synced folders can be disabled by adding the
disabled option to
Vagrant.configure("2") do |config| config.vm.synced_folder "src/", "/srv/website", disabled: true end
Disabling the default
/vagrant share can be done as follows:
config.vm.synced_folder ".", "/vagrant", disabled: true
Modifying the Owner/Group
Sometimes it is preferable to mount folders with a different owner/group than the default SSH user. Keep in mind that these options will only affect the synced folder itself. If you want to modify the owner/group of the synced folder's parent folders use a script. It is possible to set these options:
config.vm.synced_folder "src/", "/srv/website", owner: "root", group: "root"
NOTE: Owner and group IDs defined within
mount_options will have precedence
For example, given the following configuration:
config.vm.synced_folder ".", "/vagrant", owner: "vagrant", group: "vagrant", mount_options: ["uid=1234", "gid=1234"]
the mounted synced folder will be owned by the user with ID
1234 and the
group with ID
group options will be ignored.
Support for symbolic links across synced folder implementations and host/guest combinations is not consistent. Vagrant does its best to make sure symbolic links work by configuring various hypervisors (such as VirtualBox), but some host/guest combinations still do not work properly. This can affect some development environments that rely on symbolic links.
The recommendation is to make sure to test symbolic links on all the host/guest combinations you sync folders on if this is important to you.