» Vagrant and Windows Subsystem for Linux

Recent versions of Windows 10 now include Windows Subsystem for Linux (WSL) asan optional Windows feature. The WSL supports running a Linux environmentwithin Windows. Vagrant support for WSL is still in development and shouldbe considered beta.

Warning: Advanced Topic! Using Vagrant within the WindowsSubsystem for Linux is an advanced topic that only experienced Vagrant userswho are reasonably comfortable with Windows, WSL, and Linux should approach.

» Vagrant Installation

Vagrant must be installed within the Linux distribution used with WSL. Whilethe vagrant.exe executable provided by the Vagrant Windows installation isaccessible from within the WSL, it will not function as expected.

Download the installer package for the Linux distribution from the releasespage and install Vagrant.

NOTE: When Vagrant is installed on the Windows system the version installedwithin the Linux distribution must match.

» Vagrant Usage

» Windows Access

By default Vagrant will not access features available on the Windows systemfrom within the WSL. This means the VirtualBox and Hyper-V providers willnot be available. To enable Windows access, which will also enable theVirtualBox and Hyper-V providers, set the VAGRANT_WSL_ENABLE_WINDOWS_ACCESSenvironment variable:

$ export VAGRANT_WSL_ENABLE_WINDOWS_ACCESS="1"

When Windows access is enabled Vagrant will automatically adjust VAGRANT_HOMEto be located on the Windows host. This is required to ensure VAGRANT_HOMEis located on a DrvFs file system.

» PATH modifications

Vagrant will detect when it is being run within the WSL and adjust how itlocates and executes third party executables. For example, when using theVirtualBox provider Vagrant will interact with VirtualBox installed onthe Windows system, not within the WSL. It is important to ensure thatany required Windows executable is available within your PATH to allowVagrant to access them.

For example, when using the VirtualBox provider:

export PATH="$PATH:/mnt/c/Program Files/Oracle/VirtualBox"

» Synced Folders

Support for synced folders within the WSL is implementation dependent. Inmost cases synced folders will not be supported when running Vagrant withinWSL on a VolFs file system. Synced folder implementations must "opt-in" tosupporting usage from VolFs file systems. To use synced folders from withinthe WSL that do not support VolFs file systems, move the Vagrant projectdirectory to a DrvFs file system location (/mnt/c/ prefixed path for example).

» Windows Access

Working within the WSL provides a layer of isolation from the actualWindows system. In most cases Vagrant will need access to the actualWindows system to function correctly. As most Vagrant providers willneed to be installed on Windows directly (not within the WSL) Vagrantwill require Windows access. Access to the Windows system is controlledvia an environment variable: VAGRANT_WSL_ENABLE_WINDOWS_ACCESS. Ifthis environment variable is set, Vagrant will access the Windows systemto run executables and enable things like synced folders. When runningin a bash shell within WSL, the environment variable can be setup like so:

$ export VAGRANT_WSL_ENABLE_WINDOWS_ACCESS="1"

This will enable Vagrant to access the Windows system outside of theWSL and properly interact with Windows executables. This will automaticallymodify the VAGRANT_HOME environment variable if it is not already defined,setting it to be within the user's home directory on Windows.

It is important to note that paths shared with the Windows system willnot have Linux permissions enforced. For example, when a directory withinthe WSL is synced to a guest using the VirtualBox provider, any localpermissions defined on that directory (or its contents) will not bevisible from the guest. Likewise, any files created from the guest withinthe synced folder will be world readable/writeable in WSL.

Other useful WSL related environment variables:

• VAGRANT_WSL_WINDOWS_ACCESS_USER - Override current Windows username
• VAGRANT_WSL_DISABLE_VAGRANT_HOME - Do not modify the VAGRANT_HOME variable
• VAGRANT_WSL_WINDOWS_ACCESS_USER_HOME_PATH - Custom Windows system home pathIf a Vagrant project directory is not within the user's home directory on theWindows system, certain actions that include permission checks may fail (likevagrant ssh). When accessing Vagrant projects outside the WSL Vagrant willskip these permission checks when the project path is within the path definedin the VAGRANT_WSL_WINDOWS_ACCESS_USER_HOME_PATH environment variable. Forexample, if a user wants to run a Vagrant project from the WSL that is locatedat C:\TestDir\vagrant-project:

C:\Users\vagrant> cd C:\TestDir\vagrant-project
C:\TestDir\vagrant-project> bash
vagrant@vagrant-10:/mnt/c/TestDir/vagrant-project$ export VAGRANT_WSL_WINDOWS_ACCESS_USER_HOME_PATH="/mnt/c/TestDir"
vagrant@vagrant-10:/mnt/c/TestDir/vagrant-project$ vagrant ssh

» Using Docker

The docker daemon cannot be run inside the Windows Subsystem for Linux. However,the daemon can be run on Windows and accessed by Vagrant while running in theWSL. Once docker is installed and running on Windows, export the followingenvironment variable to give Vagrant access:

vagrant@vagrant-10:/mnt/c/Users/vagrant$ export DOCKER_HOST=tcp://127.0.0.1:2375