How to Install Magento 2 with WSL on Windows 11

Setting up Magento 2 on Windows 11 using Windows Subsystem for Linux (WSL) provides a powerful, efficient way to develop and test e-commerce websites without needing a dedicated Linux machine or complex virtual machines. WSL allows you to run a Linux environment directly within Windows, enabling easier management of dependencies, better performance, and a more Linux-like development experience. This guide walks you through the entire process—from installing WSL to configuring Magento 2 for local development on your Windows 11 system. Before starting, ensure your Windows 11 system is updated and that you have administrator privileges, as some steps require elevated permissions.

What You’ll Need

• Windows 11 PC with the latest updates installed
• At least 8GB RAM (16GB recommended for smoother performance)
• Microsoft Store access to install WSL distributions
• Internet connection for downloading necessary files and dependencies
• Basic familiarity with command-line interfaces (CLI)
• Optional: a code editor like Visual Studio Code for managing files

Step-by-Step

1. Enable Windows Subsystem for Linux and Virtual Machine Platform
• Open PowerShell as Administrator. You can do this by right-clicking the Start button and selecting “Windows PowerShell (Admin)”.
• Run the following commands to enable WSL and Virtual Machine Platform features:

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

• Restart your computer to apply these changes.
2. Install WSL 2 and set it as default
• After reboot, open PowerShell as Administrator again.
• Run:

 wsl --install 

• This command installs WSL 2 and the default Linux distribution (Ubuntu). If WSL is already installed, ensure WSL 2 is set as default with:

 wsl --set-default-version 2 

3. Install Ubuntu from Microsoft Store
• Open Microsoft Store, search for “Ubuntu” (preferably Ubuntu 22.04 LTS), and click “Install”.
• Once installed, launch Ubuntu from the Start menu. It will prompt you to create a UNIX username and password.
4. Update Ubuntu and install necessary packages
• In the Ubuntu terminal, run:

 sudo apt update && sudo apt upgrade -y 

• Install essential packages:

 sudo apt install apache2 mysql-server php php-cli php-common php-mbstring php-xml php-curl php-zip php-intl php-mysql php-bcmath php-soap php-gd unzip git -y 

• Ensure Apache and MySQL are enabled and running:

 sudo systemctl enable apache2 mysql sudo systemctl start apache2 mysql 

5. Configure MySQL for Magento
• Secure MySQL installation:

 sudo mysql_secure_installation 

• Create a database and user for Magento:

 sudo mysql -u root -p CREATE DATABASE magento; CREATE USER 'magento_user'@'localhost' IDENTIFIED BY 'your_password'; GRANT ALL PRIVILEGES ON magento.* TO 'magento_user'@'localhost'; FLUSH PRIVILEGES; EXIT; 

6. Download and install Composer
• In Ubuntu, run:

 php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');" php composer-setup.php php -r "unlink('composer-setup.php');" 

• Move Composer to global path:

 sudo mv composer.phar /usr/local/bin/composer 

• Verify installation:

 composer --version 

7. Download Magento 2
• Navigate to your web directory:

 cd /var/www/html 

• Download Magento via Composer:

 composer create-project --repository=https://repo.magento.com/ magento/project-community-edition magento2 

• Set permissions:

 sudo chown -R www-data:www-data /var/www/html/magento2 

8. Configure Apache Virtual Host
• Create a new configuration file:

 sudo nano /etc/apache2/sites-available/magento2.conf 

• Insert the following configuration, replacing yourdomain.test with your preferred local domain:

  ServerAdmin admin@localhost ServerName yourdomain.test DocumentRoot /var/www/html/magento2  Options Indexes FollowSymLinks MultiViews AllowOverride All Require all granted  ErrorLog ${APACHE_LOG_DIR}/magento2_error.log CustomLog ${APACHE_LOG_DIR}/magento2_access.log combined  

• Enable the site and rewrite module:

 sudo a2ensite magento2.conf sudo a2enmod rewrite sudo systemctl restart apache2 

9. Update Hosts File
• Edit Windows hosts file to map your local domain:

 Notepad.exe C:\Windows\System32\drivers\etc\hosts 

• Add the line:

 127.0.0.1 yourdomain.test 

10. Complete Magento Installation
• Open your browser and navigate to http://yourdomain.test.
• Follow the Magento Web Setup Wizard to complete the installation, entering database details, admin info, and configuration preferences.

Common Mistakes

• Not enabling WSL 2 or running it as default—leads to compatibility issues.
• Forgetting to update permissions on Magento files—causes server errors.
• Misconfiguring the Apache virtual host—results in inaccessible sites.
• Skipping MySQL secure installation—leads to insecure database setup.
• Using the wrong PHP version—Magento 2 requires specific PHP versions (7.4 or 8.1 depending on Magento version).
• Not updating the Windows hosts file—your site won’t resolve locally.

Tips

• Use a dedicated directory for Magento, such as /var/www/html/magento2, to keep things organized.
• Regularly update your WSL Ubuntu environment with

  sudo apt update && sudo apt upgrade

  .

• Consider installing phpMyAdmin or Adminer for easier database management.
• Use a local SSL certificate for development to mimic production environments.
• Backup your Magento files and database regularly, especially before updates or major changes.
• Use version control (like Git) to track changes in your Magento installation.

Troubleshooting

If you encounter issues during installation or setup, consider the following steps:

• WSL Not Starting or Commands Not Working: Ensure WSL 2 is installed correctly. Reinstall or reset WSL using

  wsl --unregister Ubuntu

  and then reinstall from Microsoft Store.

• Apache Not Serving Magento: Check your virtual host configuration and ensure Apache is restarted. Verify the correct site is enabled.
• Database Connection Errors: Double-check your MySQL credentials and ensure the database user has proper privileges.
• Magento Web Installer Not Loading: Clear your browser cache, disable any conflicting browser extensions, and verify your hosts file entry.
• PHP Errors or Missing Extensions: Confirm PHP version matches Magento requirements and all necessary PHP extensions are installed.

Frequently Asked Questions

Can I run Magento 2 on Windows without WSL?

Yes, but it’s not recommended for development; WSL provides a more compatible Linux environment.

Which version of PHP do I need for Magento 2?

Magento 2.4.x requires PHP 7.4 or 8.1, depending on the specific release.

Is WSL 2 faster than using a virtual machine?

Yes, WSL 2 offers better performance and integration with Windows compared to traditional VMs.

Can I develop multiple Magento projects on the same WSL setup?

Absolutely. Just create separate directories or virtual hosts for each project.

How do I update Magento installed via Composer?

Run

composer update

inside your Magento project directory and follow Magento update procedures.

What should I do if Magento fails to install or crashes?

Check server logs, ensure all dependencies are installed, and verify PHP and database configurations.

Setting up Magento 2 with WSL on Windows 11 streamlines local development and testing, making it easier to build and improve your e-commerce site without leaving Windows environment. Following this guide carefully ensures a smooth installation process and a robust development setup.

Related

• How to Change Startup Picture on Windows 11 Easily
• How to Change Startup Page Settings on Microsoft Edge
• How to Change Start Menu Layout in Windows 11 Easily