Posted in Magento Intermediate 11 min read

How to Install Magento 2 on Localhost: Step-by-Step Guide (2026)

Go from an empty machine to a working Magento 2.4.9 store and admin panel: PHP 8.5, MariaDB, OpenSearch, Composer, nginx and sample data, with fixes for the errors you're most likely to hit.

Veducator Team Published

A local Magento 2 store lets you build themes, test extensions and try upgrades without touching a live site. The install has more moving parts than WordPress, though: Magento needs a specific PHP version, a search engine (OpenSearch) and Composer access keys before it will even start. Skip one and the installer stops with an error that doesn’t say why.

This guide shows you how to install Magento 2 on localhost step by step, from an empty machine to a working storefront and admin panel. It uses Magento Open Source 2.4.9, the latest release (generally available since May 12, 2026), and explains every command so you know what it does.

What you need before you start

Magento only supports specific versions of each service. These are the versions Adobe lists for the current releases:

Software Magento 2.4.9 Magento 2.4.8-p5
PHP 8.5 8.4 or 8.3
Composer 2.10 2.10
MariaDB 12.3 (or 11.8) 11.4 or 11.8
MySQL 8.4 8.4
OpenSearch 3 3 (Elasticsearch 8 also works)
Web server nginx (Apache also works) nginx (Apache also works)
Magento Open Source system requirements, from Adobe's official system requirements page (October 2026).

You also need:

  • At least 4 GB of free RAM, ideally 8 GB. OpenSearch alone uses 1 GB.
  • About 5 GB of disk space for the code, the database and the generated files.
  • A free Adobe Commerce Marketplace account to get Composer access keys (step 6).
  • Basic comfort with the terminal. If you’re new to it, keep our Magento 2 CLI command list open in another tab.

Windows or Mac?

Adobe officially supports Magento only on Linux. Windows and macOS are not supported, and XAMPP or WAMP on Windows cause file-permission and symlink problems. The reliable route on Windows is WSL2 with Ubuntu, which gives you a real Linux system inside Windows. Every command below works the same in WSL2 and on a normal Ubuntu machine. On a Mac, use a Docker-based setup (see the FAQ) or an Ubuntu virtual machine.

Step 1: Prepare Ubuntu (or WSL2 on Windows)

This guide uses Ubuntu 24.04 LTS. On Windows, open PowerShell as Administrator and install Ubuntu inside WSL2:

wsl --install -d Ubuntu-24.04

Restart when asked, open “Ubuntu” from the Start menu and create your Linux user. Then update the system and install a few tools we’ll need:

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl unzip git gnupg ca-certificates software-properties-common

Tip for WSL2 users

Keep the Magento files inside the Linux file system (for example /var/www), not on /mnt/c. Magento reads thousands of files, and the Windows drive is many times slower from inside WSL2.

Step 2: Install nginx and PHP 8.5

Ubuntu 24.04 ships PHP 8.3, which Magento 2.4.9 no longer supports. The widely used ondrej/php repository provides PHP 8.5. Add it, then install nginx, PHP-FPM and every PHP extension Magento needs:

sudo add-apt-repository -y ppa:ondrej/php
sudo apt update
sudo apt install -y nginx php8.5-fpm php8.5-cli php8.5-bcmath php8.5-curl \
  php8.5-gd php8.5-intl php8.5-mbstring php8.5-mysql php8.5-soap \
  php8.5-xml php8.5-zip

The other required extensions, such as ctype, sockets, sodium, ftp and fileinfo, come with the base PHP package. In PHP 8.5, OPcache is built in. Check that nothing is missing:

php -v
php -m | grep -Ei 'bcmath|intl|soap|sodium|sockets|xsl|zip|gd'

Now raise the PHP limits Magento needs. Adobe recommends at least 1 GB of memory for compiling code and 2 GB for debugging. Apply the same settings to both PHP-FPM (the web server) and the CLI (bin/magento):

for f in /etc/php/8.5/fpm/php.ini /etc/php/8.5/cli/php.ini; do
  sudo sed -i \
    -e 's/^memory_limit = .*/memory_limit = 2G/' \
    -e 's/^max_execution_time = .*/max_execution_time = 1800/' \
    -e 's/^;*realpath_cache_size = .*/realpath_cache_size = 10M/' \
    -e 's/^;*realpath_cache_ttl = .*/realpath_cache_ttl = 7200/' \
    -e 's/^;*date.timezone =.*/date.timezone = UTC/' \
    -e 's/^;*opcache.save_comments=.*/opcache.save_comments=1/' "$f"
done
sudo systemctl restart php8.5-fpm

Replace UTC with your own time zone if you prefer, for example Asia/Kolkata or Europe/London.

Step 3: Install MariaDB and create the database

Ubuntu’s own MariaDB package is too old for Magento 2.4.9, so install MariaDB 12.3 from the official MariaDB repository:

curl -LsS https://r.mariadb.com/downloads/mariadb_repo_setup | \
  sudo bash -s -- --mariadb-server-version="mariadb-12.3"
sudo apt update
sudo apt install -y mariadb-server
sudo systemctl enable --now mariadb

Create an empty database and a user for Magento. Choose your own password: you’ll use it again in step 8.

sudo mariadb <<'SQL'
CREATE DATABASE magento2 CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
CREATE USER 'magento'@'localhost' IDENTIFIED BY 'ChangeMe_123';
GRANT ALL PRIVILEGES ON magento2.* TO 'magento'@'localhost';
FLUSH PRIVILEGES;
SQL

Step 4: Install OpenSearch

Magento won’t install without a search engine: catalog search and category pages depend on it. Add the OpenSearch 3.x repository and install it. The installer asks for an initial admin password, which must be strong (upper case, lower case, a number and a symbol):

curl -fsSL https://artifacts.opensearch.org/publickeys/opensearch-release.pgp | \
  sudo gpg --dearmor -o /usr/share/keyrings/opensearch-release-keyring
echo "deb [signed-by=/usr/share/keyrings/opensearch-release-keyring] https://artifacts.opensearch.org/releases/bundle/opensearch/3.x/apt stable main" | \
  sudo tee /etc/apt/sources.list.d/opensearch-3.x.list
sudo apt update
sudo env OPENSEARCH_INITIAL_ADMIN_PASSWORD='Local_Search_2026!' apt install -y opensearch

On a local machine you don’t need OpenSearch’s HTTPS and login layer, and leaving it on is the most common reason Magento can’t connect. Run it as a single node without the security plugin, and limit its memory to 1 GB:

sudo tee -a /etc/opensearch/opensearch.yml <<'YML'
discovery.type: single-node
network.host: 127.0.0.1
plugins.security.disabled: true
YML
sudo sed -i -e 's/^-Xms.*/-Xms1g/' -e 's/^-Xmx.*/-Xmx1g/' /etc/opensearch/jvm.options
sudo systemctl enable --now opensearch
curl http://127.0.0.1:9200

If the last command prints a block of JSON with "distribution" : "opensearch", the search engine is ready.

Local only

Turning off the OpenSearch security plugin is fine for a local machine that only listens on 127.0.0.1. Never do it on a server that can be reached from the internet.

Step 5: Install Composer

Magento is downloaded and managed with Composer, the PHP package manager. Install the latest version globally:

curl -sS https://getcomposer.org/installer -o composer-setup.php
sudo php composer-setup.php --install-dir=/usr/local/bin --filename=composer
rm composer-setup.php
composer --version

Step 6: Get your Magento access keys

Magento’s packages are hosted on repo.magento.com, which needs a free key pair:

  1. Sign in or create an account at commercemarketplace.adobe.com.
  2. Click your name, then go to My Profile → Access Keys.
  3. Click Create A New Access Key and give it a name, for example “localhost”.
  4. Copy the Public Key (this is your Composer username) and the Private Key (your password).

Treat the private key like a password. Don’t commit it to Git or paste it into public forums.

Step 7: Download Magento 2 with Composer

Create the project folder, make your user its owner, and download Magento Open Source 2.4.9. Composer asks for a username and password: paste the public key and the private key from step 6, then answer Y to save them.

sudo mkdir -p /var/www/magento2
sudo chown $USER:www-data /var/www/magento2
cd /var/www/magento2
composer create-project --repository-url=https://repo.magento.com/ \
  magento/project-community-edition=2.4.9 .

The download takes a few minutes. When it finishes, set the file permissions. Your user stays the owner, and the web server (the www-data group) gets write access only to the folders Magento writes to:

cd /var/www/magento2
find var generated vendor pub/static pub/media app/etc -type f -exec chmod g+w {} +
find var generated vendor pub/static pub/media app/etc -type d -exec chmod g+ws {} +
sudo chown -R :www-data .
chmod u+x bin/magento
sudo usermod -aG www-data $USER

Log out and back in (or close and reopen the WSL2 window) so your user picks up the new group.

Step 8: Run the Magento installer

This command creates the database tables, the admin account and the configuration file. Change the values to your own, especially the database password from step 3 and the admin details:

bin/magento setup:install \
  --base-url=http://magento.local/ \
  --db-host=localhost \
  --db-name=magento2 \
  --db-user=magento \
  --db-password='ChangeMe_123' \
  --admin-firstname=Admin \
  --admin-lastname=User \
  --admin-email=admin@example.com \
  --admin-user=admin \
  --admin-password='Admin_12345' \
  --backend-frontname=admin \
  --language=en_US \
  --currency=USD \
  --timezone=UTC \
  --use-rewrites=1 \
  --search-engine=opensearch \
  --opensearch-host=127.0.0.1 \
  --opensearch-port=9200

The installer runs for several minutes. It ends with [SUCCESS]: Magento installation complete. and prints your admin URI. The admin password must be at least 7 characters long and contain both letters and numbers, or the installer stops.

Installer stopped with an error?

Fix the cause and run the same command again: the installer is safe to rerun. The usual causes are listed in the troubleshooting table further down.

Step 9: Configure nginx and the local domain

Magento includes a ready-made nginx configuration, nginx.conf.sample. You only need a small file that points to it and tells nginx where PHP-FPM is listening:

upstream fastcgi_backend {
    server unix:/run/php/php8.5-fpm.sock;
}

server {
    listen 80;
    server_name magento.local;
    set $MAGE_ROOT /var/www/magento2;
    include /var/www/magento2/nginx.conf.sample;
}

Save it with sudo nano /etc/nginx/sites-available/magento.conf, then enable it and reload nginx:

sudo ln -s /etc/nginx/sites-available/magento.conf /etc/nginx/sites-enabled/
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t && sudo systemctl reload nginx

Finally, point magento.local to your own machine by adding this line to your hosts file:

127.0.0.1   magento.local
  • Ubuntu: edit /etc/hosts with sudo nano /etc/hosts.
  • Windows with WSL2: open Notepad as Administrator and edit C:\Windows\System32\drivers\etc\hosts. Your Windows browser then reaches nginx inside WSL2.

Step 10: Finish the setup for local development

A few commands make the local store much easier to work with. Run them from /var/www/magento2:

# Show errors and skip caching of static files while you develop
bin/magento deploy:mode:set developer

# Two-factor authentication blocks the admin login without a mail server
bin/magento module:disable Magento_AdminAdobeImsTwoFactorAuth Magento_TwoFactorAuth

# Rebuild everything and clear the cache
bin/magento setup:upgrade
bin/magento indexer:reindex
bin/magento cache:flush

# Run Magento's scheduled jobs (indexing, emails) every minute
bin/magento cron:install

Two-factor authentication

Disable 2FA only on your local copy. Keep it on for any store that is online, including staging sites.

Now open http://magento.local/ to see the storefront (it’s empty for now) and http://magento.local/admin to sign in with the admin user from step 8. Congratulations: Magento 2 is running on localhost.

Step 11 (optional): Install sample data

An empty store isn’t much use for testing a theme. Magento’s sample data adds products, categories, CMS pages and orders from the “Luma” demo store:

bin/magento sampledata:deploy
bin/magento setup:upgrade
bin/magento indexer:reindex
bin/magento cache:flush

The deploy step uses the same Composer keys from step 6. Reload the storefront and you’ll see a full demo shop.

Troubleshooting common installation errors

Error or symptom Cause and fix
Could not validate a connection to OpenSearch OpenSearch isn't running or still uses HTTPS. Run sudo systemctl status opensearch and check that curl http://127.0.0.1:9200 works (step 4).
Your requirements could not be resolved (Composer) Wrong PHP version or missing extension. Check php -v (8.5 for 2.4.9) and php -m.
Allowed memory size exhausted Raise memory_limit to 2G in **both** CLI and FPM php.ini, then restart php8.5-fpm.
Invalid credentials for repo.magento.com Wrong access keys. Use the **public** key as username. Fix them in ~/.config/composer/auth.json.
Storefront has no CSS or images Static files are missing or not writable. Rerun the permission commands from step 7, then bin/magento setup:static-content:deploy -f.
404 Not Found on every page nginx isn't using the Magento config or the root is wrong. Check set $MAGE_ROOT and run sudo nginx -t.
502 Bad Gateway PHP-FPM isn't running or the socket path differs. Check ls /run/php/ and sudo systemctl status php8.5-fpm.
Permission denied in var/ or generated/ The web server can't write there. Rerun the step 7 commands and make sure your user is in the www-data group.
Fixes for the errors you are most likely to see when installing Magento 2 locally.

Frequently asked questions

Can I install Magento 2 on XAMPP or WAMP?

You can get older versions running, but it isn’t recommended. Windows is not a supported platform, XAMPP rarely ships the PHP version current Magento needs, and you still have to install OpenSearch separately. WSL2 takes the same effort and behaves like a real server, so what works locally also works when you deploy.

Is there a faster way with Docker?

Yes. Community tools such as Mark Shust’s docker-magento, Warden and DDEV start nginx, PHP, MariaDB and OpenSearch in containers with a few commands. They are a good choice on a Mac, or when you work on several stores with different versions. Installing manually once, as in this guide, still helps you understand what those tools do for you.

Which Magento version should I install?

Install the version your live store runs, so your tests match production. For a new project, use the latest release, 2.4.9. If you need PHP 8.3 or 8.4, use 2.4.8-p5 and change =2.4.9 to =2.4.8-p5 in step 7.

How much RAM does Magento need locally?

Plan for at least 4 GB free, with 8 GB for comfortable work. OpenSearch is set to use 1 GB in this guide, and compiling code with setup:di:compile needs another 1–2 GB.

How do I install Magento extensions after setup?

Most extensions are installed with Composer and then enabled with bin/magento. Follow our step-by-step guide on how to install Magento 2 extensions.

Can I use this local copy to test upgrades?

Yes, that’s one of the best reasons to have it. Copy your live database and code to your local machine, then follow our guide on how to upgrade Magento 2 before you touch production.

Conclusion

Installing Magento 2 on localhost comes down to matching the requirements exactly: PHP 8.5, MariaDB 12.3 or MySQL 8.4, OpenSearch 3 and Composer with your Marketplace keys. Set those up in order, run the installer, point nginx at nginx.conf.sample and switch to developer mode. You’ll have a full store to build and test on, with no risk to your live site.

Need a Magento store built, upgraded or sped up? Request a free quote and we’ll get back to you with a plan and a price.

Before you go

Key takeaways

  • Magento runs on Linux. On Windows, use WSL2 with Ubuntu instead of XAMPP or WAMP.
  • Match the requirements exactly: Magento 2.4.9 needs PHP 8.5, MariaDB 12.3 or MySQL 8.4, and OpenSearch 3.
  • Get free access keys from the Adobe Commerce Marketplace before running composer create-project.
  • Install with bin/magento setup:install, then include nginx.conf.sample in your nginx config.
  • For local work, switch to developer mode and disable 2FA, but never on a live store.

Written by Veducator Team

Working developers who build and maintain WordPress and Magento sites for a living.

All Magento tutorials