Skip to main content
Logo
Overview
Installing Trellis on WSL

Installing Trellis on WSL

September 12, 2022
2 min read
wordpress
roots
trellis
devops
ansible

Updates

As of 2025-10-23, Trellis has dropped Vagrant and Parallels in favor of Lima VMs. This means Trellis on Windows is not supported at this time.

Introduction

Roots Trellis is a complete WordPress server setup that ensures consistency across local development, staging, and production environments. While it’s traditionally easier to set up on MacOS, this guide will help you set it up on Windows using Windows Subsystem for Linux (WSL).

Key Points

  • Use WSL Version 1 for Roots Trellis setup
  • Install Ubuntu 20.04 (not 22.04) as Trellis currently runs on this version
  • All commands must be run from WSL

Installation Steps

1. Install WSL

Follow the official guide to install WSL. Make sure to install Ubuntu 20.04.

2. Install Global Dependencies

Once Ubuntu 20.04 is installed, you’ll need these core services:

PHP 8.1

Terminal window
sudo add-apt-repository ppa:ondrej/nginx
sudo apt update
sudo apt install php8.1 php8.1-mbstring php8.1-xml php8.1-zip

Homebrew

Terminal window
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Composer

Terminal window
brew install composer

NFS Server

Terminal window
sudo apt update
sudo apt install nfs-kernel-server

3. Install Trellis Dependencies

Trellis relies on the following software tools:

  • VirtualBox >= 6.1.38 (install on Windows)
  • Vagrant >= 2.2.16 (install on both Windows and WSL)
  • Ansible >= 2.10.7 (install in WSL)

VirtualBox

Download and install the latest version of VirtualBox for Windows from the official website.

Vagrant

Install the same version (2.2.16) of Vagrant in both Windows and WSL.

For WSL:

Terminal window
curl -O https://releases.hashicorp.com/vagrant/2.2.16/vagrant_2.2.16_x86_64.deb
curl -O https://releases.hashicorp.com/vagrant/2.2.16/vagrant_2.2.16_SHA256SUMS
curl -O https://releases.hashicorp.com/vagrant/2.2.16/vagrant_2.2.16_SHA256SUMS.sig
curl -sS https://keybase.io/hashicorp/key.asc | gpg --import
gpg --verify vagrant_2.2.16_SHA256SUMS.sig vagrant_2.2.16_SHA256SUMS
shasum -a 256 -c <(cat vagrant_2.2.16_SHA256SUMS | grep 64.deb) -s
sudo apt install ./vagrant_2.2.16_x86_64.deb

Configure Vagrant to communicate with Windows and VirtualBox by adding the following to your .bashrc:

Terminal window
export PATH="$PATH:/mnt/c/Program Files/Oracle/VirtualBox"
export VAGRANT_WSL_ENABLE_WINDOWS_ACCESS="1"

Ansible

Install Ansible in WSL:

Terminal window
brew install pipx
pip3 install ansible-core==2.10.7 --user

If the above doesn’t work, try:

Terminal window
sudo apt install ansible

Troubleshooting

SSH Issues

If vagrant ssh doesn’t work, try:

Terminal window
echo 'alias vssh="ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no vagrant@127.0.0.1 -i ./.vagrant/machines/default/virtualbox/private_key -p"' >> ~/.bashrc
source ~/.bashrc

Slow Site

Install the vagrant-winnfsd plugin:

Terminal window
vagrant plugin install vagrant-winnfsd
vagrant reload # if Vagrant was already running

If problems persist, try forcing TCP instead of UDP by adding nfs_udp: false to the NFS mount point configuration in your Vagrantfile.

Permission Issues

Add the following to /etc/wsl.conf in your WSL instance:

[automount]
options = "metadata,umask=22,fmask=11"

Then restart WSL and apply correct permissions:

Terminal window
chmod -R 744 trellis
chmod 600 [path_to_ssh_key_file]

Conclusion

This setup process, while complex, allows you to use Roots Trellis effectively on Windows with WSL. Trellis provides a robust development environment for WordPress, ensuring consistency across different stages of your project’s lifecycle.