How to install Moodle™: step-by-step installation and setup guide

To install Moodle™ you need four things in place: a web server with PHP, a database, a copy of the Moodle code and a private data directory. This guide walks through the whole Moodle installation on a Linux server (Ubuntu), with shorter notes for Windows and local test installs, the first settings to change afterwards, and fixes for the problems that most often stall a new site.

Moodle’s version requirements change with every release, so where a number matters we show the pattern and link to the official page to confirm it. If you are still deciding whether the platform fits, start with our overview of what Moodle is and how it works.

What you need before you install Moodle

A Moodle server setup goes smoothly when the server meets the requirements and a few decisions are made in advance. Check these four areas first.

Moodle system requirements

Each release has its own minimums, published in the official Moodle release notes. The table shows what the release notes list for Moodle 5.2; the same figures are published for the 5.3 long-term support (LTS) release. Older branches such as 4.5 LTS accept older PHP and database versions, so always check the page for the version you are installing.

Oracle is no longer supported from Moodle 5.0. The soap and openssl extensions are recommended if you plan to use web services or integrations.

Server sizing

The documented hardware minimums will run a small pilot, not a busy site. Size the server for the number of people online at the same time, the volume of files and video you will store, and whether the database shares the machine. Leave room to grow: moving a live site to a bigger server is harder than starting with headroom.

Domain, HTTPS and email

• A domain or subdomain that points to the server, such as learn.example.com.
• A TLS certificate, so the whole site runs on HTTPS from the first day.
• An SMTP service or mail relay. Moodle sends account confirmations, password resets and notifications by email.

Planning questions

Three answers shape how you set up Moodle once it is running:

• Who are the learners? Internal staff are usually a known list managed by an administrator. Customers and partners often need self-registration or bulk account creation.
• How will courses be delivered? Self-paced, instructor-led or blended delivery changes which activities and plugins you need.
• How will accounts be created? Options include integration with a directory, HR or student information system, a CSV upload, or self-registration.

Choose where to run Moodle

• Your own server or a VPS. You get full control and take on patching, backups, performance and security. This is the path the step-by-step section covers. A cloud virtual machine is installed the same way.
• A local test install. A laptop or virtual machine is fine for evaluating Moodle or testing plugins, and should not hold real learner data.
• Shared web hosting. It can work if the host meets the PHP and database minimums and lets you change the document root and add a cron job. Confirm all three before you pay.
• MoodleCloud. Moodle’s own hosted service suits individuals and small organizations that want no server work. Our guide to MoodleCloud explains who it fits.
• Managed hosting. A provider installs, secures and upgrades the site for you. Our comparison of self-hosting and a managed service covers the trade-offs.

Moodle download: package or Git

Only take the code from Moodle’s own sources. There are two ways to get it:

• Download a package. download.moodle.org offers the latest stable release and every other supported version as .tgz and .zip files.
• Clone with Git. The official documentation recommends Git because later updates become a single pull. Each major release has a branch named in the pattern MOODLE_502_STABLE (5.2) or MOODLE_501_STABLE (5.1).

Choose the latest stable release for the newest features, or an LTS release if you want fewer major upgrades. According to the release schedule, LTS versions receive security fixes for three years, compared with about 18 months for a standard release.

One change affects every recent install. From Moodle 5.1, the code contains a public directory and the web server must serve only that directory. config.php and other sensitive files sit one level above it. Tutorials that point the web server at the Moodle folder itself were written for Moodle 5.0 and earlier, including 4.5 LTS.

Moodle installation on Ubuntu, step by step

These steps install Moodle on Ubuntu Server (a current LTS release) with Apache and MariaDB. They assume Moodle 5.1 or later in /var/www/moodle, data in /var/moodledata and an account with sudo rights. The sequence is the same on Debian. Other Linux distributions use different package names and a different web server user (often apache instead of www-data). The official Installing Moodle page is the reference for anything not covered here.

1. Install the web server, PHP, the database and Git.

   sudo apt update
   sudo apt install apache2 mariadb-server git php libapache2-mod-php php-cli php-mysql php-curl php-gd php-intl php-mbstring php-xml php-zip php-soap

   Run php -v and mariadb --version and compare the results with the release notes. If the packages are older than the minimums, move to a newer OS release before going further. To use PostgreSQL, install postgresql and php-pgsql in place of mariadb-server and php-mysql.

2. Raise max_input_vars. Set max_input_vars = 5000 in the php.ini files used by Apache and by the command line (on Ubuntu, under /etc/php/ in the apache2 and cli folders for your PHP version), then restart Apache:

   sudo systemctl restart apache2

3. Create the database and a dedicated user. Open the database shell with sudo mariadb and run:

   CREATE DATABASE moodle DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   CREATE USER 'moodleuser'@'localhost' IDENTIFIED BY 'use-a-strong-password';
   GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,CREATE TEMPORARY TABLES,DROP,INDEX,ALTER ON moodle.* TO 'moodleuser'@'localhost';
   EXIT;

   Never let Moodle connect as the database root user. On PostgreSQL, create a UTF8 database owned by a dedicated role instead.

4. Get the Moodle code. Swap the branch name for the release you chose:

   cd /var/www
   sudo git clone -b MOODLE_502_STABLE https://github.com/moodle/moodle.git moodle
   sudo chown -R root /var/www/moodle
   sudo chmod -R 0755 /var/www/moodle

   If you downloaded a package instead, extract it to /var/www/moodle and apply the same ownership. The code should not be writable by the web server user.

5. Create the moodledata directory. This holds uploaded files, cache and session data. It must sit outside any web-accessible folder and belong to the web server user:

   sudo mkdir /var/moodledata
   sudo chown www-data:www-data /var/moodledata
   sudo chmod 0700 /var/moodledata

6. Point Apache at the public directory. Create /etc/apache2/sites-available/moodle.conf:

   <VirtualHost *:80>
       ServerName learn.example.com
       DocumentRoot /var/www/moodle/public
       <Directory /var/www/moodle/public>
           AllowOverride None
           Require all granted
           FallbackResource /r.php
       </Directory>
   </VirtualHost>

   Then enable the site:

   sudo a2ensite moodle
   sudo a2dissite 000-default
   sudo systemctl reload apache2

   For Moodle 5.0 or earlier, use /var/www/moodle as the document root. Moodle documents the equivalent settings for Nginx.

7. Add HTTPS. Install a TLS certificate for the domain (Let’s Encrypt is a common free option) and enable the HTTPS site before you run the installer, so the site address you enter starts with https://.

8. Run the Moodle install script. The command-line installer is the recommended method. It needs temporary write access to the Moodle folder to create config.php:

   sudo chown www-data /var/www/moodle
   cd /var/www/moodle/admin/cli
   sudo -u www-data /usr/bin/php install.php
   sudo chown -R root /var/www/moodle

   The installer asks for the language, site address, data directory, database details, site name and administrator account. Add --help to see the options for an unattended install.

   Prefer a browser? Open the site address and the web installer asks the same questions. If it cannot write config.php, it offers the file as a download; upload it to the Moodle root folder, not to public. Keep the site unreachable from the internet until the installer has finished.

9. Set up cron. Moodle’s background tasks send email, run backups and process queued work. Open the web server user’s crontab:

   sudo crontab -u www-data -e

   Add this line so the cron script runs every minute, as Moodle recommends:

   * * * * * /usr/bin/php /var/www/moodle/admin/cli/cron.php >/dev/null

10. Log in and check the environment. Sign in as the administrator and open Site administration > Server > Environment. Every row should pass before you invite anyone else.

Installing Moodle on Windows or a local machine

Quick test packages. Moodle publishes installer packages for Windows that bundle Apache, MySQL and PHP using XAMPP, and similar packages for macOS built with MAMP. Both download pages warn that the bundled software does not meet the database minimums for recent Moodle versions and must not be used on a production server. Treat them as a way to look around, nothing more.

A realistic Moodle local installation. Run a Linux virtual machine on your computer and follow the Ubuntu steps above, using http://localhost as the site address. A site installed with a localhost address only displays correctly on that machine; use the machine’s network name or IP address if other people need to reach it.

Production on Windows Server. The Windows installation documentation describes a manual build with Apache or IIS, PHP and MariaDB, MySQL or PostgreSQL. The installer steps are the same, and cron runs as a task in Windows Task Scheduler. Moodle is developed mainly on Linux, so that remains the better-documented route.

First setup after installation

1. Site basics. Set the site name, default time zone and support contact under Site administration.
2. Email. Enter your SMTP details at Site administration > Server > Email > Outgoing mail configuration, then use the test outgoing mail page to confirm delivery.
3. Security checks. Open Site administration > Reports > Security checks and resolve the warnings. Confirm every page loads over HTTPS.
4. Backups. Automate backups of the database, the moodledata directory and the code including config.php. Store copies off the server and practise a restore.
5. Theme and branding. Add your logo and colours. Our guide to choosing a Moodle theme compares the options.
6. Plugins. Add only what you need, and only versions that support your release. See our list of the best Moodle plugins for a starting point.
7. Users and courses. Add accounts one at a time or with a CSV file at Site administration > Users > Accounts > Upload users. Create a course at Site administration > Courses > Add a new course, then enrol people from the course’s Participants page.
8. Performance. Enable PHP OPcache, and plan a dedicated cache store such as Redis for larger sites.

Common Moodle installation problems and fixes

• The environment check fails. The message names what is missing: a PHP version, an extension, max_input_vars or a database version. Install or change it and restart the web server.
• A blank page. Read the web server error log first. A common cause is PHP lacking the driver for your database. Turning on debugging in config.php shows the real error.
• “Not found” errors on Moodle 5.1 or later. The document root must be the public directory, with unmatched requests falling back to r.php.
• Pages load without styles or images. The site address in config.php ($CFG->wwwroot) does not match the address people use, often because it was set to localhost.
• Data directory errors. The moodledata folder must exist, sit outside the web root and be writable by the web server user.
• No email, or tasks never finish. Cron is not running. Check the crontab entry, then the outgoing mail settings.
• Uploads are rejected. Raise Moodle’s maximum uploaded file size, then upload_max_filesize and post_max_size in php.ini. Nginx also needs client_max_body_size.
• “Composer vendor directory not found”. This status check appears on Moodle 5.1 and later when Composer dependencies are missing. With Composer installed on the server, run composer install --no-dev --classmap-authoritative in the Moodle root folder.

The official Installation FAQ covers more cases. Before asking for help in the Moodle community forums, note your Moodle, PHP and database versions and the exact error text.

Keeping your Moodle site updated and secure

Moodle publishes a major release roughly every six months and minor releases with fixes in between. Plan each upgrade before security support for your version ends.

1. Read the release notes and confirm that every plugin and theme has a compatible version.
2. Back up the code, the moodledata directory and the database.
3. Rehearse the upgrade on a copy of the site.

4. Run the upgrade. For a minor update on a Git install:

   cd /var/www/moodle
   sudo -u www-data /usr/bin/php admin/cli/maintenance.php --enable
   sudo git pull
   sudo -u www-data /usr/bin/php admin/cli/upgrade.php
   sudo -u www-data /usr/bin/php admin/cli/maintenance.php --disable

Moving to a new major release means switching branch, as described in Git for Administrators. Coming from 5.0 or earlier, you also need to change the document root and move added plugins into public.

Between upgrades, keep the operating system, PHP and database patched, restrict the firewall to the ports you need, and monitor disk space, logs and response times. Keep a written record of configuration changes, customizations and plugin versions. Moodle’s security recommendations list the rest.

When to skip the self-install

Installing Moodle is a one-time job. Running it is ongoing: patching, upgrades, backups, monitoring and capacity. If nobody on your team owns that work, MoodleCloud suits small sites with standard needs. Organizations that need their own plugin set, integrations, Canadian data residency or hands-on support usually choose managed Moodle hosting, where the provider handles installation and upkeep.

Frequently asked questions

What are the minimum requirements for Moodle?

Moodle needs a web server, PHP, a supported database and a mail service. For Moodle 5.2 the release notes list PHP 8.3 or 8.4 (64-bit) and PostgreSQL 16, MariaDB 10.11, MySQL 8.4 or SQL Server 2019. The documentation recommends at least 5GB of disk and 1GB or more of memory. Always confirm against the release notes for your version.

How do I install Moodle on Windows?

For testing, download the Windows package from download.moodle.org, which bundles Apache, MySQL and PHP; Moodle warns it must not be used in production. For a real site on Windows, install Apache or IIS, PHP and a supported database manually, run the Moodle installer and schedule cron with Task Scheduler. A Linux server is the better-documented route.

How do I install Moodle on a Mac?

Moodle publishes Mac packages built with MAMP that include Apache, MySQL and PHP. They are meant for local testing, and the download page warns that MAMP’s bundled MySQL does not meet the database minimum for Moodle 5.0, so do not use them in production. A Linux virtual machine that follows the Ubuntu steps gives a more realistic test site.

How do I install a Moodle theme or plugin?

Download the version that matches your Moodle release from the Moodle Marketplace, which has replaced the old plugins directory. Upload the ZIP at Site administration > Plugins > Install plugins, or unzip it into the correct folder on the server and visit Site administration > Notifications. The web upload only works if the web server can write to that folder. Installing plugins has the details.

How do I uninstall Moodle?

Save anything you want to keep, then remove three things: drop the Moodle database, delete the moodledata directory and delete the Moodle code directory. Remove the cron entry and the web server site configuration as well. The web server, PHP and database packages stay on the machine and can be removed separately if nothing else uses them.

Can I install Moodle on AWS or another cloud provider?

Yes. A cloud virtual machine running Linux is installed like any other server: web server, PHP, database, code, moodledata, installer and cron. Larger sites often move the database, file storage and cache onto separate services, which adds design and operations work. Without that expertise in-house, managed hosting is usually the safer choice.

Lambda Learning is a Canadian company that installs, hosts and maintains Moodle so your team does not have to. If you would rather spend your time on courses than on servers, book a call with our team and we will walk through your requirements.