Joomla tutorials by Joomlaboratory

Many jobs on a Joomla site have to happen on a schedule: clearing old action logs, checking in locked items, cleaning expired sessions, sending update notifications or calling an external URL. Since Joomla 4.1 these jobs are handled by the built-in Task Scheduler. You create a task once, and Joomla runs it at the interval you set.

The scheduler still needs something to start it. Joomla gives you three ways to do that: the Lazy Scheduler, Web Cron and the command line (CLI) started by a real server cron job. This guide covers all three, explains when to use each one, and shows how to set them up step by step.

1. Key concepts

• Cron is the Unix/Linux service that runs commands on a schedule, for example every minute or every night at 03:00. Most hosting control panels (cPanel, Plesk, DirectAdmin) have a "Cron Jobs" screen for it.
• Scheduled Task is one job defined inside Joomla, such as "Delete Action Logs older than 90 days". Each task has a type, its own settings and an execution rule (how often it runs).
• Trigger is what wakes up the scheduler so it can check which tasks are due. The trigger does not decide what runs. It only starts the check. The three triggers are described below.

So you always need two things: tasks defined in Joomla, and one trigger that starts the scheduler regularly.

2. Creating a scheduled task

1. In the Administrator, go to System → Manage → Scheduled Tasks.
2. Click New and choose a task type. The available types come from Task plugins. Common core types include Delete Action Logs, Global Check-in, Session Data Purge, Update Notification, Rotate Logs, Set Site Status (offline/online) and GET Request (calls any URL). Third-party extensions can add their own.
3. Give the task a clear title and fill in its options on the Task tab.
4. Under Execution Rule, pick an interval (minutes, hours, days or months) or Cron Expression for full control. For example, 0 3 * * * runs every day at 03:00.
5. Save. The list shows each task's Last Run and Next Run. You can also click Run Test to run a task immediately and check that it works.

If a task type is missing, check that the matching plugin is enabled in System → Manage → Plugins (filter by type task).

3. Method A: the Lazy Scheduler (default)

The Lazy Scheduler is enabled on a fresh installation. When someone visits the site, a small script on the page sends a background request to Joomla, which then runs any tasks that are due.

How to configure it

1. Go to System → Manage → Scheduled Tasks and click Options.
2. Open the Lazy Scheduler tab.
3. Set Lazy Scheduler to Enabled or Disabled, and choose the Request Interval, the minimum number of seconds between two checks.

Pros and cons

• Pro: no server access or configuration needed. It works out of the box.
• Con: it depends on visitors. With no traffic (at night, or on an intranet), tasks do not run.
• Con: timing is not exact, and long tasks run inside a visitor's request, which uses web server resources.

Use it when the site is small, tasks are light and timing is not important.

4. Method B: Web Cron

With Web Cron, an outside caller requests a special Joomla URL on a fixed schedule. That caller can be your hosting control panel or an online cron service such as cron-job.org or EasyCron. Each request starts the scheduler.

How to enable it

1. Go to System → Manage → Scheduled Tasks → Options.
2. Open the Web Cron tab and set Web Cron to Enabled.
3. Joomla generates a secret Key (hash). Save, then copy the trigger URL shown on that tab. It looks like this:

https://www.example.com/index.php?option=com_ajax&plugin=RunSchedulerWebcron&group=system&format=json&hash=YOUR_SECRET_KEY

To run a single task only, add its ID: &id=5.

Calling the URL on a schedule

From a hosting control panel (cPanel → Cron Jobs, Plesk → Scheduled Tasks), add a job that runs every minute with:

curl -s "https://www.example.com/index.php?option=com_ajax&plugin=RunSchedulerWebcron&group=system&format=json&hash=YOUR_SECRET_KEY" > /dev/null

If curl is not available, use wget -q -O /dev/null "URL".

From an online cron service, create an account, paste the URL and choose the interval. This is useful when your hosting has no cron feature at all.

Pros and cons

• Pro: runs on time even without visitors, and does not need shell or PHP CLI access.
• Con: it still goes through the web server, so long tasks can hit PHP max_execution_time or web server timeouts.
• Con: the URL contains a secret. Anyone who has it can trigger your tasks.

Use it when you have no SSH or PHP CLI access, for example on basic shared hosting.

5. Method C: CLI with a server cron job (recommended)

Joomla includes a console application, cli/joomla.php. Its scheduler commands run tasks directly through PHP, without HTTP, secret keys or web server timeouts. This is the most reliable method.

Useful commands

Run php cli/joomla.php list scheduler to see every option on your Joomla version.

Setting up the cron job

1. Find the right PHP binary. It must be the same PHP version your site uses. On many hosts php points to an older default version. Common paths are /usr/bin/php8.3 or, on cPanel, /opt/cpanel/ea-php83/root/usr/bin/php. Check with php -v.
2. Find the absolute path of your Joomla root, for example /home/username/public_html.
3. Add the cron entry. Over SSH, run crontab -e, or use your control panel's Cron Jobs screen:

* * * * * /usr/bin/php8.3 /home/username/public_html/cli/joomla.php scheduler:run --all > /dev/null 2>&1

This starts the scheduler every minute. Joomla then runs only the tasks that are actually due, according to each task's own execution rule, so running every minute is safe and keeps timing accurate.

To keep a log file instead of discarding the output, replace the end of the line with >> /home/username/logs/joomla-cron.log 2>&1.

Reading cron syntax

A cron line has five time fields followed by the command:

┌──────── minute (0–59)
│ ┌────── hour (0–23)
│ │ ┌──── day of month (1–31)
│ │ │ ┌── month (1–12)
│ │ │ │ ┌ day of week (0–6, Sunday = 0)
│ │ │ │ │
* * * * *  command

The same syntax works in a task's Cron Expression execution rule inside Joomla.

On Windows (local development)

Use Windows Task Scheduler: create a task that repeats every minute and starts C:\path\to\php.exe with the arguments C:\path\to\site\cli\joomla.php scheduler:run --all.

Pros and cons

• Pro: accurate, independent of traffic, and no PHP execution time limit for long tasks.
• Pro: no public URL and no secret key to protect.
• Con: needs cron access with PHP CLI on the server.

Use it when your hosting allows it. In practice, this is almost always the best choice.

6. Which method should I choose?

Important: once you set up Web Cron or a CLI cron job, disable the Lazy Scheduler (Options → Lazy Scheduler). Otherwise visitors keep triggering tasks as well, which adds needless load to page views.

7. Security tips

• Treat the Web Cron key like a password. Do not share it or put it in public repositories. If it leaks, generate a new key in Options.
• Always call the Web Cron URL over HTTPS.
• If you do not use Web Cron, leave it disabled.
• Run the CLI cron job as the same system user that owns the site files. Running it as root can create cache or log files the website cannot write to later.

8. Troubleshooting

• Tasks never run: check that at least one trigger is active, the task is published, and its Next Run time has passed. Use scheduler:list to check from the CLI.
• CLI errors about the PHP version or missing extensions: cron is using a different PHP binary from your site. Use the full path to the correct version.
• "Could not open input file": the path to cli/joomla.php is wrong. Always use absolute paths in cron.
• A task is stuck as running (locked): if a previous run crashed, the task stays locked. Open the task list and use Unlock, then fix the cause.
• Web Cron returns an error or 403: check that Web Cron is enabled, the key in the URL matches the one in Options, and the System – Schedule Runner plugin is enabled. Also check that no firewall or security extension blocks com_ajax requests.
• Tasks run twice: more than one trigger is active, for example the Lazy Scheduler together with a cron job. Disable the ones you do not need.

Summary

Define your tasks in System → Scheduled Tasks, then choose a single trigger. If your server allows it, use a CLI cron job running every minute. If you cannot use the CLI, use Web Cron. Keep the Lazy Scheduler for simple sites only. Once a real trigger is in place, disable the Lazy Scheduler so every task runs exactly once, on time.