Magento 2: How to Install Magento 2 on Windows using WSL2, Docker, and VS Code: Full Step-by-Step Guide with Real Errors and Fixes

How to Install Magento 2 on Windows using WSL2, Docker, and VS Code: Full Step-by-Step Guide with Real Errors and Fixes

Installing Magento 2 in a Windows environment using WSL2 and Docker can be tricky if you're new to the stack. In this detailed blog post, I’ve documented my complete experience, including every real error I encountered and solutions. Whether you're setting up Magento for the first time or helping a friend, this guide will walk you through every step.

🧰 Prerequisites

Windows 10/11 with WSL2 enabled
Ubuntu installed via Microsoft Store
Docker Desktop (with WSL2 integration)
Visual Studio Code with Dev Containers extension
Magento 2 source code (fetched from Magento Marketplace)
Composer
Apache
MySQL or MariaDB
PHP (8.2)
Elasticsearch or OpenSearch

✅ Step 1: Enable WSL2 and Install Ubuntu

Open PowerShell as Administrator and run:
```
wsl --install
```
Restart your system.
Go to the Microsoft Store → Search for Ubuntu 22.04 LTS → Install.
Launch Ubuntu, set your username and password.

✅ Step 2: Install Docker Desktop

Download from https://www.docker.com/products/docker-desktop
During installation, enable WSL2 Integration.
Go to Settings → Resources → WSL Integration and enable for Ubuntu.

✅ Step 3: Install VS Code & Dev Containers

Install Visual Studio Code
Install the Dev Containers extension from the Extensions Marketplace.
Clone or copy your Magento 2 source code to a folder.
Open that folder in VS Code → Reopen in Container (when prompted).

✅ Step 4: Install Apache, MySQL, PHP, Elasticsearch and Required Packages

sudo apt update && sudo apt upgrade -y
sudo apt install php8.2 php8.2-common php8.2-mysql php8.2-xml php8.2-curl php8.2-cli php8.2-bcmath php8.2-gd php8.2-intl php8.2-mbstring php8.2-soap php8.2-zip php8.2-xdebug php8.2-opcache -y
sudo apt install apache2 mysql-server unzip curl git -y

✅ Step 5: Fix PHP Version to 8.2

sudo update-alternatives --set php /usr/bin/php8.2
php -v

✅ Step 6: Install Composer

curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer
composer --version

✅ Step 7: Fix Composer Performance

composer config --global process-timeout 2000
composer clear-cache

✅ Step 8: Configure Magento Marketplace Auth

composer config --global http-basic.repo.magento.com <public_key> <private_key>

✅ Step 9: Create Magento 2 Project

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

✅ Step 10: Set SQL Variables (Important)

sudo nano /etc/mysql/mysql.conf.d/mysqld.cnf

Add or edit:

sql-mode=""

Then:

sudo service mysql restart

✅ Step 11: Install and Start Elasticsearch or OpenSearch

sudo apt install apt-transport-https openjdk-11-jdk wget -y
wget -qO - https://artifacts.opensearch.org/publickeys/opensearch.pgp | sudo apt-key add -
echo "deb https://artifacts.opensearch.org/releases/bundle/opensearch/2.x/apt stable main" | sudo tee /etc/apt/sources.list.d/opensearch-2.x.list
sudo apt update && sudo apt install opensearch -y
sudo systemctl start opensearch.service
sudo systemctl enable opensearch.service

✅ Step 12: Install Magento 2

php bin/magento setup:install \
--base-url=http://magento2.local \
--db-host=localhost \
--db-name=magento \
--db-user=magento \
--db-password=magento@123 \
--admin-firstname=Admin \
--admin-lastname=User \
--admin-email=admin@example.com \
--admin-user=admin \
--admin-password=Admin@123 \
--language=en_US \
--currency=USD \
--timezone=Asia/Kolkata \
--use-rewrites=1

✅ Step 13: Setup Apache Virtual Host

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

Add:

<VirtualHost *:80>
    ServerName magento2.local
    DocumentRoot /var/www/html/magento2/pub

    <Directory /var/www/html/magento2/pub>
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/magento2_error.log
    CustomLog ${APACHE_LOG_DIR}/magento2_access.log combined
</VirtualHost>

Enable site:

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

✅ Step 14: Update Windows Hosts File

Find WSL IP:

ip addr show eth0 | grep inet

In Windows Notepad (Run as Admin), add:

<WSL_IP> magento2.local

✅ Step 15: Set Permissions

sudo chown -R $USER:www-data .
sudo find var generated vendor pub/static pub/media app/etc -type f -exec chmod g+rw {} \;
sudo find var generated vendor pub/static pub/media app/etc -type d -exec chmod g+rwxs {} \;

✅ Step 16: Composer Install

composer install

✅ Step 17: Fix GitHub OAuth Token Issues (If any)

If you see:

Your github oauth token for github.com contains invalid characters: ""

Fix it with:

composer config --global --auth --unset github-oauth.github.com
composer config --global --auth github-oauth.github.com YOUR_NEW_TOKEN

Or edit manually:

mkdir -p ~/.config/composer
nano ~/.config/composer/auth.json

And add:

{
  "github-oauth": {
    "github.com": "YOUR_NEW_TOKEN"
  }
}

✅ Step 18: Check Apache, MySQL, PHP Status

sudo systemctl status apache2
sudo systemctl status mysql
php -v

To start if stopped:

sudo systemctl start apache2
sudo systemctl start mysql

✅ Step 19: Common Magento Commands

php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f
php bin/magento cache:flush
tail -n 50 var/log/exception.log

Thanks for reading - Happy Code

Magento 2

Pages

How to Install Magento 2 on Windows using WSL2, Docker, and VS Code: Full Step-by-Step Guide with Real Errors and Fixes