Kickstart your Laravel 10 using Laravel Sail (WSL2) 【Updated 2023】

7 min readMar 11, 2023

You may be familiar with the VirtualBox with Homestead in the Laravel dev environment. However, this traditional hosted virtual machine comes with an extra layer of overhead before accessing your real hardware resources.

These few years, you might hear about Containerization (or Docker) all over the Internet. Instead of virtualizing the whole VM, it packages up the code and all its dependencies as a “Container”. You can learn more about containers here… You might be still using Laradock… Finally, in December 2020, Taylor Otwell released Laravel Sail!

Laravel Sail is a light-weight command-line interface for interacting with Laravel’s default Docker development environment.
Sail provides a great starting point for building a Laravel application using PHP, MySQL, and Redis without requiring prior Docker experience.
Source: Laravel Documentation

For this tutorial, I will take you to kickstart your brand new Laravel project on Windows using WSL 2. WSL stands for Windows Subsystem for Linux, it allows developers to run Linux environments directly on Windows without any “real” hosted VM. WSL 2 is a major overhaul and provides the benefits of WSL 1 with better file IO performance (20x faster). It is not like the traditional VM which may be slow to boot up, has a large resource overhead, and be fully isolated.

Let’s turn on your WSL 2 on your Windows machine!

(Optional) Enable Hyper-V

Run your PowerShell with Administrator right and then execute

Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All

Reboot the computer after the installation.

WSL is using the subset of HyperV components, and installing these tools may help in some situations, for example, multiple adapters which are connecting to local and internet networks simultaneously.

(Optional) Enable Windows Hypervisor Platform

If you are still using VirtualBox or other 3rd Party virtualization software (e.g. VMware), you may need to turn on this optional feature.

Run your PowerShell with Administrator right and then execute

Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform

🐧 Install WSL 2

🛠️ Simplified Install (Windows 11 / Windows 10 version 2004 or higher)
1. Open a command window with administrator privileges (Run As Administrator) and run
wsl --install, after a restart, you will be ready to use WSL.

If the command is not available for your Windows 10 build, try the manual installation below. Alternatively, you can look for KB5004296 for more details.

2. Use wsl --list --verbose to verify your installation

If you encounter any issues, you may refer to some troubleshooting tips here.

If VMware workstation is installed and you encounter this message “Please enable the Virtual Machine Platform Windows feature and ensure virtualization is enabled in the BIOS.”, you can execute this command bcdedit /set hypervisorlaunchtype auto.

🛠️ Manual Install (Skip this section if you’re using the latest Win 10/11)
(Windows 10 Build 18362 or higher, including Home Edition)

1. Enable WSL

Open a command window with administrator privileges then run

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

2. Enable the Virtual Machine feature

Virtualization capabilities are still required for WSL 2. Open a command window with administrator privileges then run

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

3. Download the Linux kernel update package

Download WSL2 Linux kernel update package for x64 machines and install it.

Then, restart your computer.

4. Set WSL 2 as your default version

wsl --set-default-version 2

5. Install Ubuntu (or Linux distribution of your choice)

I ) Open the Microsoft Store and then search & select Ubuntu.
II ) From the distribution page, select “Get” then select “Install”
III) Click “Launch” when it is ready
IV ) Create your username and password for your Ubuntu

6. Use wsl --list --verbose to verify your installation

If you encounter any issues, you may refer to some troubleshooting tips here.

If VMware workstation is installed and you encounter this message “Please enable the Virtual Machine Platform Windows feature and ensure virtualization is enabled in the BIOS.”, you can execute this command bcdedit /set hypervisorlaunchtype auto.

🐳 Install Docker

1. Download
Download Docker Desktop Stable.

2. Install
Follow the installation wizard to install the Docker Desktop. If your WSL 2 is configured properly, it should prompt you to use WSL 2 during installation.

In the Docker menu, select **Settings** > **General** : Make sure WSL 2 is enabled.

3. Configure WSL Integration
Make sure you turn on the correct Linux distros.

In the Docker menu, select **Settings** > **Resources** > **WSL Integration**

⛵ Let’s Sail

Launch the Windows Terminal and key in wsl

Here is the catch… You may notice the path is your mounted Windows user directory.
On the official Microsoft WSL documentation, it stated the comparison. WSL 2 architecture outperforms WSL 1 in several ways, with the exception of performance across OS file systems.

Image Credit: The exception of performance across OS file systems. (Comparing WSL 1 and WSL 2)

⚠️ The documentation stated…

We recommend against working across operating systems with your files, unless you have a specific reason for doing so.
For example, when storing your WSL project files:
✔️ Use the Linux file system root directory:
\\wsl$\Ubuntu-18.04\home\<user name>\Project
❌ Not the Windows file system root directory:
C:\Users\<user name>\Project

We can go to your Linux home directory by using cd ~

Let’s create a new Laravel project called test-project using this command:

curl -s https://laravel.build/test-project | bash

Then wait for the installation

You may wonder how you access your Laravel project files. You can access it via the network share \\wsl$

\\wsl$\Ubuntu\home\<user name>\test-project

The actual location of the WSL storage (in vhdx format) is located at
C:\Users\<user name>\AppData\Local\Packages\ CanonicalGroupLimited.UbuntuonWindows_79rhkp1fndgsc\LocalState

Now we can get into the directory cd test-project and start to Sail!

./vendor/bin/sail up

The first time running sail up takes some time to download the docker images and build up your container but it will be very fast for the next run.

If you encounter any issue, your Antivirus software might be the culprit. Please make the exclusion for the path “C:\ProgramData\DockerDesktop\vm-data\” .

You can see your container up and running…

Once the container has been started, you can go to http://localhost to access your brand-new Laravel project.

📦 Pick your Sail stack

The default stack included mysql, redis, meilisearch, mailhog, and selenium. Available services include mysql, pgsql, mariadb, redis, memcached, meilisearch, selenium, and mailhog.

You can pick your favorite stack using with query:

curl -s "https://laravel.build/example-app?with=mysql,redis" | bash

It will be configuring your docker-compose.yml file accordingly.

🕗 Daily Sail routine

Start Sail in detached mode

./vendor/bin/sail up -d

Stop Sail

Control + C if you are not using “detached” mode, otherwise

./vendor/bin/sail down

Alias

Instead of typing a long path name, configure a Bash alias that allows you to call sail directly

alias sail='[ -f sail ] && sh sail || sh vendor/bin/sail'

You may create an alias permanently add the alias to your .bashrc file
use nano ~/.bashrc then add alias sail='[ -f sail ] && sh sail || sh vendor/bin/sail' at the bottom
then run . ~/.bashrc

💾 Start your coding

✍️ Visual Studio Code

Make sure you install the plugin Remote — WSL extension, for other useful Laravel development extensions for VS Code you can refer to this — Here is my VS Code for Laravel.

Make sure you are in the project folder

cd ~/test-project/

Then run

code .

You should be able to see the VS Code launch and show your project folder

Now you can start coding and preview your change at http://localhost

✍️ PhpStorm

You can open the project using \\wsl$\Ubuntu\home\<user>\test-project

💡 Tip: You can call artisan command using sail artisan <command>

Happy Coding! 💪💪💪

💡 Tip: Connecting your SQL Management Software using localhost with the default username: sail and password: password.

Video Demo

💡 Troubleshooting: If you encounter “port has already been allocated" issue,
you can run the following command with Administrator right:
net stop winnat netsh int ipv4 set dynamic tcp start=49152 num=16384 netsh int ipv6 set dynamic tcp start=49152 num=16384 net start winnatSource: https://github.com/docker/for-win/issues/3171#issuecomment-788808021

More about Laravel Sail Performance, Debugging, Hot-Reload, Swoole HTTPS, Multisite with Custom Domain and more are coming… Follow me to get the latest updates! Thanks for reading 😉

Are you ready to put your sites online with unlimited app hosting for only $14 per month?

Cloudways comes with tons of features that make you easily host your Laravel, WordPress, or any PHP sites without worrying about cyber-securities nightmares.

Now you can extra discount during the BFCM 2023 campaign period!

Let’s start trying the Cloudways!