How to Set Up Moodle Cron Correctly

Moodle cron is the heartbeat behind scheduled email, forum notifications, enrolment processing, automated backups and dozens of plugin jobs. A site may appear normal while cron is failing, then gradually develop delayed messages, stuck queues and incomplete background work.

Moodle recommends running the cron script every minute. That does not mean every task runs every minute; cron checks the schedule and launches only work that is due.

Use the command-line cron method

On a server where PHP CLI is available, schedule Moodle’s CLI script as the web-server user:

* * * * * /usr/bin/php /path/to/moodle/public/admin/cli/cron.php >/dev/null 2>&1

For Moodle 5.1 and later, web-accessible code is normally under the public directory, so confirm the real location on your installation. Older layouts may use /path/to/moodle/admin/cli/cron.php.

Do not copy the example path without checking it. Locate the PHP CLI binary, the Moodle code directory and the operating-system account that owns or runs the web process. Shared hosting panels often provide a Cron Jobs screen where the same command can be entered.

Test the command before scheduling it

Run the command manually as the intended service user. A successful run prints task information and finishes without a PHP fatal error. If the command uses a different PHP version from the website, extensions or configuration can differ, so compare CLI and web PHP versions.

Check Moodle’s task pages

Open Site administration > Server > Tasks > Scheduled tasks. Review:

• Last run and Next run times.
• Tasks highlighted red, which can indicate repeated failures.
• A growing fail delay.
• Tasks disabled intentionally or by a disabled plugin.

Moodle 5.3 also includes task-processing controls and a Run ASAP option for eligible tasks. Run ASAP places work in the queue for cron instead of keeping a browser request open. It still depends on working cron.

Verify overall health

Go to Site administration > Reports > System status. Check the cron frequency, maximum task fail delay, ad hoc queue and long-running tasks. A queue that continually grows is a symptom; increasing frequency alone may not fix a task that crashes, locks or waits on an external service.

Web cron versus CLI cron

Moodle can expose a web cron endpoint, but CLI is generally the better production choice because it avoids web timeouts and can run under a controlled account. If remote web cron is unavoidable, configure the cron password and restrict access. Never publish a cron URL containing its secret.

Useful diagnostic commands

php public/admin/cli/scheduled_task.php --list
php public/admin/cli/scheduled_task.php --execute
php public/admin/cli/adhoc_task.php --execute

Paths differ before Moodle 5.1. Run individual tasks only when you understand their effect, especially on a production site. Moodle’s locking prevents the same scheduled task from running concurrently, but external scripts and custom plugins can still create load.

Common cron failures

• Command not found: use the absolute PHP CLI path.
• Wrong Moodle path: confirm whether the installation uses the newer public layout.
• Permission denied: run under an appropriate service account and review file permissions.
• Different PHP errors: CLI may load another php.ini or PHP version.
• Tasks stay queued: inspect scheduled and ad hoc task pages, logs, locks and external-service dependencies.
• Email remains delayed: test SMTP separately; cron cannot deliver through a broken mail configuration.

Production checklist

• Cron starts every minute.
• Only one deliberate scheduler entry exists per site.
• The command uses absolute paths.
• CLI and web PHP meet the same Moodle requirements.
• System status has no unexplained task warnings.
• Server monitoring alerts when cron stops.

Final advice

Do not wait for users to report missing mail. Treat cron as a monitored service and review failed tasks after plugin installs and upgrades. For a better learner-facing experience once the server is healthy, see Themes Almond Moodle themes.

Source check: Verified against Moodle 5.3 documentation for Scheduled tasks, command-line administration and the System status report.