Skip to main content
This guide covers two paths to a working local MediaWiki installation: a Docker-based setup that mirrors the Wikimedia development environment, and a lightweight manual setup using PHP’s built-in web server with SQLite — the fastest way to start hacking on MediaWiki code.

​
System requirements

MediaWiki 1.46.0 requires:

PHP

PHP 8.2.0 or higher with the following extensions enabled: ctype, dom, fileinfo, iconv, intl, json, libxml, mbstring, openssl, xml, xmlreader

Database

One of:
  • MariaDB 10.3+
  • MySQL 5.7.0+
  • PostgreSQL 10+
  • SQLite 3.31.0+

Web server

Any web server capable of running PHP: Apache 2, Nginx with PHP-FPM, or PHP’s built-in server (for development only).

Composer

Composer 2 for dependency management. All PHP dependencies are declared in composer.json and must be installed before MediaWiki will run.
On 32-bit systems, either the bcmath or gmp PHP extension is also required. These extensions are also needed for scrambling Temporary Accounts on any architecture.
Recommended optional extensions for a complete development experience:
ExtensionPurpose
ext-apcuFaster web responses via in-memory caching
ext-curlFaster HTTP client (InstantCommons, Swift, Etcd)
ext-gdImage thumbnail generation for file uploads
ext-mysqliMySQL/MariaDB database driver
ext-pdoSQLite database driver
ext-pgsqlPostgreSQL database driver

​
Two setup paths

# 1. Clone the MediaWiki source
git clone https://gerrit.wikimedia.org/r/mediawiki/core mediawiki
cd mediawiki

# 2. Install PHP dependencies
composer install

# 3. Create the .env file (no .env.example — create it manually)
cat > .env << 'EOF'
MW_SCRIPT_PATH=/w
MW_SERVER=http://localhost:8080
MW_DOCKER_PORT=8080
MEDIAWIKI_USER=Admin
MEDIAWIKI_PASSWORD=dockerpass
XDEBUG_CONFIG=
XDEBUG_ENABLE=true
XHPROF_ENABLE=true
EOF
echo "MW_DOCKER_UID=$(id -u)" >> .env
echo "MW_DOCKER_GID=$(id -g)" >> .env

# 4. Start all services (PHP-FPM, Apache, job runner)
docker compose up -d

# 5. Wait for services, then open http://localhost:8080/w/index.php

​
Docker setup

1

Clone and install dependencies

Clone the MediaWiki repository and install all Composer dependencies. The composer install step fetches all packages declared in composer.json, including Wikimedia libraries, Parsoid, OOjs UI, and development tooling.
git clone https://gerrit.wikimedia.org/r/mediawiki/core mediawiki
cd mediawiki
composer install
2

Configure the environment

The Docker Compose setup reads from a .env file. Create one manually (there is no .env.example):
cat > .env << 'EOF'
MW_SCRIPT_PATH=/w
MW_SERVER=http://localhost:8080
MW_DOCKER_PORT=8080
MEDIAWIKI_USER=Admin
MEDIAWIKI_PASSWORD=dockerpass
XDEBUG_CONFIG=
XDEBUG_ENABLE=true
XHPROF_ENABLE=true
EOF
echo "MW_DOCKER_UID=$(id -u)" >> .env
echo "MW_DOCKER_GID=$(id -g)" >> .env
Windows users: leave MW_DOCKER_UID and MW_DOCKER_GID blank in the .env file.
The docker-compose.yml defines three services:
ServiceImageRole
mediawikibookworm-php83-fpm:1.0.0-s1PHP 8.3 FPM application server
mediawiki-webbookworm-apache2:1.0.1Apache 2 reverse proxy, port 8080
mediawiki-jobrunnerbookworm-php83-jobrunner:1.0.0-s1Background job runner
The repository root is mounted at /var/www/html/w inside each container. SQLite data and logs are stored in the cache/ directory.
3

Start the services

docker compose up -d
Confirm all three containers are running:
docker compose ps
4

Install MediaWiki

First install Composer dependencies inside the container, then run the install script:
# Install PHP dependencies inside the container
docker compose exec mediawiki composer update

# Run the Docker install script (creates the database and LocalSettings.php)
docker compose exec mediawiki /bin/bash /docker/install.sh
Windows users: the install script must be run from PowerShell, not Bash.
5

Verify the installation

Open http://localhost:8080/w/index.php in your browser. You should see the MediaWiki main page. Log in with username Admin and password dockerpass.Confirm the Action API responds:
curl "http://localhost:8080/w/api.php?action=query&meta=siteinfo&format=json&formatversion=2"

​
Manual install with composer serve

1

Clone and install dependencies

git clone https://gerrit.wikimedia.org/r/mediawiki/core mediawiki
cd mediawiki
composer install
2

Run the SQLite installer

The mw-install:sqlite Composer script runs the CLI installer with flags suited for local development:
composer mw-install:sqlite
This is equivalent to:
php maintenance/run.php install \
  --server=http://localhost:4000 \
  --dbtype=sqlite \
  --with-developmentsettings \
  --dbpath=cache/ \
  --scriptpath= \
  --pass=adminpassword \
  MediaWiki Admin
The --with-developmentsettings flag enables verbose errors and the debug toolbar. The SQLite database file is created in cache/.
3

Start the development server

composer serve
This starts PHP’s built-in web server on http://127.0.0.1:4000 with 8 worker processes (PHP_CLI_SERVER_WORKERS=8). Logs are written to logs/ and mirrored to stderr.
PHP 8.2.x Development Server (http://127.0.0.1:4000) started
PHP’s built-in server is not suitable for production. Use it only for local development.
4

Verify the installation

Open http://127.0.0.1:4000 in your browser. Log in with username Admin and password adminpassword.Test the Action API:
curl "http://127.0.0.1:4000/api.php?action=query&meta=siteinfo&format=json&formatversion=2"
Test the REST API:
curl "http://127.0.0.1:4000/rest.php/v1/page/Main_Page"

​
Development environment

After the basic install, a few more steps give you a complete development setup:
1

Run the unit test suite

PHPUnit is included in the dev dependencies. Run the unit tests (no database required):
composer phpunit:unit
Run the full test suite (requires a database):
composer phpunit
2

Run code quality checks

# PHP syntax check
composer lint .

# PHPCS code style (MediaWiki coding standards)
composer phpcs .

# Run all checks
composer test
3

Use the maintenance runner

The maintenance Composer script is a shorthand for php maintenance/run.php. Use it to run any maintenance script:
# Rebuild the localisation cache
composer maintenance rebuildLocalisationCache.php

# Apply database schema changes after a code update
composer maintenance update.php
For Xdebug and XHProf profiling in the Docker setup, set XDEBUG_ENABLE=true and XHPROF_ENABLE=true in your .env file. Both are enabled by default in docker-compose.yml.

Build docs developers (and LLMs) love

Get started for freeTalk to us