How to Install Magento 2 with WSL on Windows 11

Install Windows Subsystem for Linux in 🪟 Windows 11

You install Windows Subsystem for Linux with a single command in an elevated Command Prompt. WSL is a built-in Windows feature that gives you a Linux environment on your PC without a virtual machine. The steps are: open Command Prompt as an administrator, run the install command, and restart the 🔄 computer to finish the core setup.

First, open Command Prompt with administrator rights. Without them, the install command will fail.

1. Click the Start button and type Command Prompt.
2. Right-click the Command Prompt app and choose Run as administrator.
3. If Windows asks Do you want to allow this app to make changes to your device?, click Yes. A black console window opens with a title that starts with “Administrator”.

Now install WSL from the console you just opened.

1. Run the commands below in the Command Prompt window.

wsl --install

Wait for WSL to be installed. This can take a few minutes, depending on your connection, because Windows downloads the Linux components. Don’t close the window while it works.

When the install finishes, you should get a success message similar to the lines below. If you see an error instead, check that virtualization is turned on in your PC's BIOS or UEFI settings, then run the command again.

Installing: Virtual Machine Platform
Virtual Machine Platform has been installed.
Installing: Windows Subsystem for Linux
Windows Subsystem for Linux has been installed.
Downloading: WSL Kernel
Installing: WSL Kernel
WSL Kernel has been installed.
Downloading: GUI App Support
Installing: GUI App Support
GUI App Support has been installed.
Downloading: Ubuntu
The requested operation is successful. Changes will not be effective until the system is rebooted.

Restart your computer. The restart is required. WSL won't work properly until Windows has restarted.

After the restart, WSL should be installed and ready to use. To update it later, open Command Prompt and run the commands below:

wsl --update

Install Specific Linux distro on 🪟 Windows 11

You install a specific Linux distribution by first listing the ones available online from your terminal. Ubuntu is the most common choice, and it provides the operating system that Magento's web tools run on. Check the online list with a terminal command, then install the distribution you want.

wsl --list --online

Run the command above. You should then see all the distributions that you can install on WSL.

NAME                                   FRIENDLY NAME
Ubuntu                                 Ubuntu
Debian                                 Debian GNU/Linux
kali-linux                             Kali Linux Rolling
Ubuntu-18.04                           Ubuntu 18.04 LTS
Ubuntu-20.04                           Ubuntu 20.04 LTS
Ubuntu-22.04                           Ubuntu 22.04 LTS
Ubuntu-24.04                           Ubuntu 24.04 LTS
openSUSE-Leap-15.6                     openSUSE Leap 15.6
SUSE-Linux-Enterprise-15-SP6           SUSE Linux Enterprise 15 SP6

To install a distribution from the list, run the install command with the distribution's name. Copy the name exactly as it appears in the list. For example, to install Ubuntu 20.04, run the commands below:

wsl --install -d ubuntu-20.04

Wait for the download to finish. You should then get a message that the distribution is installed.

Downloading: Ubuntu 20.04 LTS
Installing: Ubuntu 20.04 LTS
Ubuntu 20.04 LTS has been installed.
Launching Ubuntu 20.04 LTS.

After the install, an Ubuntu command console opens with setup details. It asks you to create a Linux username and password. These are separate from your Windows account. Remember the password, because you'll need it for every sudo command later in this guide.

Installing, this may take a few minutes.
Please create a default UNIX user account. The username does not need to match your Windows username.
For more information visit: https://aka.ms/wslusers
Enter new UNIX username: Richard
New password:
Retype new password:
passwd: password updated successfully
Installation successful!
To run a command as administrator (user "root"), use "sudo <command>".
See "man sudo_root" for details.

Welcome to Ubuntu 20.04 LTS (GNU/Linux 4.4.0-22000-Microsoft x86_64)

If you run into problems with WSL or your distribution, try the troubleshooting commands below.

wsl --set-default-version 2
bcdedit /set hypervisorlaunchtype auto

Install Nginx HTTP Server

You install the Nginx HTTP server inside your Ubuntu environment by refreshing the package lists and then running the install command. Nginx is the web server that delivers your site's pages to visitors. Update the package lists first so you get the newest versions, then install Nginx to prepare Ubuntu for hosting Magento.

Do the following in your Ubuntu console, not in Command Prompt.

1. Run the commands below to update the package lists and install Nginx.

sudo apt update
sudo apt install nginx

After installing Nginx, you can use the commands below to stop, start, and restart the Nginx service. If a page won't load later, restarting the service is the first thing to try.

sudo service nginx stop
sudo service nginx start
sudo service nginx restart

To check that Nginx is installed and working, open your web browser and go to the server's hostname or IP address. When you browse from the same PC, localhost normally works too.

If everything works, you should see the Nginx test page.

http://localhost

Install MariaDB Database Server

You install the MariaDB database server on your WSL Ubuntu setup with the package manager, installing both the server and client components. MariaDB stores your website content, user accounts, and product catalog. Download and set up the database software so Magento has somewhere to save its data.

MariaDB is a truly open-source database server you can use with your projects. It is fast, secure, and the default database server on almost all Linux distributions.

To install MariaDB, run the commands below in your Ubuntu console:

sudo apt-get install mariadb-server mariadb-client

After installing MariaDB, you can use the commands below to stop, start, and restart the MariaDB service.

sudo service mysql stop
sudo service mysql start
sudo service mysql restart

Next, run the commands below to secure the database server and set a root password. You need this step even if the installer didn't prompt you for a password.

sudo mysql_secure_installation

When prompted, answer the questions as shown below. Choose a strong root password and write it down, because you'll use it again when you create the Magento database.

• Enter current password for root (enter for none): Press Enter
• Set root password? [Y/n] : Y
• New password: Enter password
• Re-enter new password: Repeat password
• Remove anonymous users? [Y/n] : Y
• Disallow root login remotely? [Y/n] : Y
• Remove test database and access to it? [Y/n] : Y
• Reload privilege tables now? [Y/n] : Y

To check that MariaDB is installed and working, log in to the database console with the commands below:

sudo mysql -u root -p

Type the root password when prompted. The cursor won't move and no characters appear while you type. That is normal.

Welcome to the MariaDB monitor.  Commands end with ; or g.
Your MariaDB connection id is 46
Server version: 10.3.29-MariaDB-0ubuntu0.20.04.1 Ubuntu 20.04
Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.
Type 'help;' or 'h' for help. Type 'c' to clear the current input statement.
MariaDB [(none)]>

The server is installed and working if you see a screen like the one below.

Install PHP and Related Modules

You install PHP and its related modules with a single command that includes the extensions e-commerce software needs. Magento relies heavily on PHP and a specific set of modules to process orders and display pages. Install the full package list at once so your server doesn't miss a required extension. Also check which PHP version your Magento release supports, because each release supports only certain versions.

To install PHP and the recommended modules, run the commands below.

sudo apt install php-fpm php-common php-mysql php-gmp php-curl php-intl php-mbstring php-xmlrpc php-gd php-xml php-cli php-zip php-soap php-bcmath

That installs PHP with the recommended modules that most PHP-based applications use.

To check that PHP is installed, run the commands below:

php -v

You should see output like the one below. It shows the installed PHP version.

PHP 7.4.3 (cli) (built: Oct  6 2020 15:47:56) ( NTS )
Copyright (c) The PHP Group
Zend Engine v3.4.0, Copyright (c) Zend Technologies
with Zend OPcache v7.4.3, Copyright (c), by Zend Technologies

You can also test with a PHP script. It displays the installed version and which modules are enabled or disabled.

1. Run the commands below to create a PHP test file called phpinfo.php

sudo nano /var/www/html/phpinfo.php

1. In the editor that opens, type the content below.

<?php phpinfo( ); ?>

1. Save the file and close the editor.

1. Open your browser and go to your server hostname followed by phpinfo.php.

1. Restart Nginx with the commands below, then type the address and browse to the file again.

http://example.com/phpinfo.php

You should see the PHP default test page. If the browser downloads the file or shows the raw code instead, Nginx is not yet passing PHP files to PHP. Check your Nginx configuration and restart the service. Once the test works, delete the test file, because it exposes details about your server.

At this point, every component Magento needs is installed. Continue below to create the database, then download and configure Magento.

Create Magento Database

You create the Magento database by logging in to the MariaDB console as root and running a few SQL commands. The database is a dedicated space that keeps your store's records separate from other applications. Open the database prompt, create the database and a user for it, and then exit so MariaDB saves the changes.

1. Log in to the MariaDB console with the commands below, and enter the root password when prompted.

sudo mysql -u root -p

1. Create a database called magentodb

CREATE DATABASE magentodb;

1. Create a database user called magentodbuser and set a password. Replace the sample password with your own strong one.

CREATE USER 'magentodbuser'@'localhost' IDENTIFIED BY 'new_password_here';

1. Grant the user full access to the database.

GRANT ALL ON magentodb.* TO 'magentodbuser'@'localhost' WITH GRANT OPTION;

1. Save your changes and exit the console.

FLUSH PRIVILEGES;
EXIT;

Download Magento

You download the Magento source code into your WSL environment by installing a few transfer tools, such as curl and git, and then fetching the project files. Getting the official package lets you build your store locally for testing and development. Install the command-line tools first, then download the Magento files into your web server directory.

To get Magento's latest release, you can use the GitHub repository. Install Composer, curl, and the other dependencies first by running the commands below.

sudo apt install curl git
curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin --filename=composer

When prompted, enter your authentication keys. Your public key is your username; your private key is your password. ( https://marketplace.magento.com/customer/accessKeys/ )

You have to register for a Magento Marketplace account to create the keys above. Create the account and the keys before you continue.

After installing curl and Composer, change into the Nginx root directory and download the Magento packages from GitHub with the commands below. Always replace the branch number with the latest branch.

To see the available Magento releases, check this page.

cd /var/www/
sudo composer create-project --repository=https://repo.magento.com/ magento/project-community-edition magento

When Composer asks for authentication, copy and paste your keys. Your public key is your username; your private key is your password. The download takes a while, so let it finish.

Output:
Authentication required (repo.magento.com):
Username: 234f2343435d190983j0ew8u3220
Password: 
Do you want to store credentials for repo.magento.com in /opt/magento/.config/composer/auth.json ? [Yn] Y

After downloading the Magento packages, run the commands below to install Magento with the following options. Replace the sample values, such as the database password and admin details, with your own.

Elasticsearch is installed with the Magento packages. If you run into issues after the previous steps, you can turn off the Elasticsearch module with the command below. This deactivates the module.

sudo php bin/magento module:disable {Magento_Elasticsearch,Magento_InventoryElasticsearch,Magento_Elasticsearch6,Magento_Elasticsearch7}

If you want to run Magento with Elasticsearch instead, read this post.

You must set the correct permissions for Magento 2 to work properly. For example, `sudo find . -type f -exec chmod 444 {} \;` and `sudo find . -type d -exec chmod 555 {} \;` make sure Magento 2 can read and access its files and directories. These settings make files read-only. If Magento later complains that it can't write to a folder, check the permissions on that folder.

The `www-data` user needs to own your Magento directory so Nginx and PHP can run Magento 2 correctly. Run the `sudo chown -R www-data:www-data /var/www/html/magento2` command to give the `www-data` user ownership of the Magento directory and everything in it.

sudo chown -R www-data:www-data /var/www/magento/
sudo chmod -R 755 /var/www/magento/

Configure Nginx VirtualHost

You configure an Nginx VirtualHost for your Magento site by creating a new configuration file in the server's sites directory. The file tells Nginx where your website files are and how to handle incoming browser requests. Create the server block file with your domain details so you can reach your local store in a web browser.

1. Run the commands below to create a new VirtualHost file called Magento in the /etc/nginx/sites-available/ directory.

sudo nano /etc/nginx/sites-available/magento

Below is a solid configuration for most Magento sites on Nginx. It should work for this setup.

1. Copy the content below and paste it into the file you just created.

upstream fastcgi_backend {
  server unix:/run/php/php7.4-fpm.sock;
}

server {
    listen 80;
    listen [::]:80;

    server_name  example.com www.example.com;
    index  index.php;

    set $MAGE_ROOT /var/www/magento;
    set $MAGE_MODE production;

    access_log /var/log/nginx/example.com-access.log;
    error_log /var/log/nginx/example.com-error.log;

    include /var/www/magento/nginx.conf.sample;
}

1. Save the file and exit the editor.

After saving the file, run the commands below to enable the new site and restart the Nginx server. The restart is needed for Nginx to load the new configuration.

sudo ln -s /etc/nginx/sites-available/magento /etc/nginx/sites-enabled/
sudo service nginx restart

Magento is now ready. Launch it by browsing to the server's IP address or hostname.

https://example.com

That should bring up the Magento home page.

Log in with the admin account you created during the Magento install, and you're done.

That's it!

Conclusion:

This post showed you how to install Magento on Windows 11 with Ubuntu on WSL. If you find any error above, please use the comment form below to report it.