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
