WordPress has a built-in scheduling system called WP-Cron that lets you run tasks at specific intervals. Despite its name, WP-Cron isn’t a true cron job. Understanding the difference — and the limitations — is essential for building reliable scheduled tasks into your plugins.
This guide covers everything you need to know about WordPress cron jobs: how they work, when to use them, common pitfalls, and how to replace WP-Cron with a real system cron for reliability.
How WP-Cron Works (And Why It’s Different)
A true system cron job runs at a specific time, regardless of whether anyone visits the site. WP-Cron works differently: it checks the schedule only when someone visits the site. If a task is scheduled for 3:00 AM and nobody visits until 9:00 AM, the task runs at 9:00 AM.
This behavior is fine for low-traffic sites where timing isn’t critical. But for sites that need tasks to run at exact times — like sending scheduled emails or processing recurring payments — WP-Cron’s lazy evaluation can cause problems.
Scheduling Tasks with wp_schedule_event
The primary function for scheduling recurring tasks is wp_schedule_event(). It takes three parameters: a timestamp for the first execution, a recurrence interval, and a hook name to execute. The hook should match an action you’ve registered with add_action().
Always check whether the event is already scheduled before calling wp_schedule_event(). Use wp_next_scheduled() to check for existing schedules. Schedule your events on plugin activation using the register_activation_hook() and clean up on deactivation with register_deactivation_hook().
Custom Recurrence Intervals
WordPress provides four built-in recurrence intervals: hourly, twicedaily, daily, and weekly. If you need a different interval, use the cron_schedules filter to register a custom schedule. Provide an array with an interval in seconds and a display name for the WordPress admin.
Custom schedules are useful for tasks like sending weekly digest emails, cleaning up expired data every 6 hours, or checking for updates every 5 minutes for real-time features.
Single Events with wp_schedule_single_event
For tasks that run once at a specific time, use wp_schedule_single_event(). This is useful for delayed actions like sending a reminder email 24 hours after a user signs up, or processing a refund 7 days after a purchase if no return is requested.
Single events are stored in the wp_options table with a timestamp. When the timestamp passes and someone visits the site, the task executes and the event is removed from the schedule automatically.
Long-Running Tasks and Performance
WP-Cron runs inline with page requests. If a cron task takes 30 seconds to complete, the visitor whose request triggered it will wait 30 seconds for the page to load. This is unacceptable for long-running tasks like email campaigns, image processing, or data exports.
For long-running tasks, use wp_remote_post() to trigger a separate HTTP request that runs the task asynchronously. Send a request to a special URL on your site with a secret key for authentication. The task runs in a separate process, and the visitor’s page load isn’t affected.
Replacing WP-Cron with System Cron
For sites that need reliable scheduling, replace WP-Cron with a real system cron job. Disable WP-Cron by adding define(‘DISABLE_WP_CRON’, true) to wp-config.php. Then set up a system cron job on your server that calls wp-cron.php at your desired interval.
A typical system cron job runs every 5 minutes and calls the WordPress cron file: curl -s https://yoursite.com/wp-cron.php > /dev/null 2>&1. This provides true cron behavior — tasks run exactly when scheduled, regardless of site traffic. It also improves performance for visitors because WP-Cron isn’t checked on every page load.
Debugging Cron Issues
Cron issues can be difficult to debug because they happen in the background. Use WP-CLI to list scheduled events with wp cron event list. Check for missed events with wp cron event run –all. Enable WP_DEBUG logging to capture cron-related errors. Use plugins like WP Crontrol or Advanced Cron Manager to view and manage cron schedules from the admin dashboard.
Common cron problems include: events not being scheduled due to activation hook not firing, events running multiple times due to race conditions, and events failing silently due to PHP errors. Each of these has specific debugging approaches that can help you identify the root cause.
The Bottom Line
WP-Cron is a powerful system for scheduling tasks in WordPress, but it has limitations that you need to understand. Use it for short, frequent tasks where exact timing isn’t critical. Replace it with a real system cron for tasks that must run at precise times. Always handle errors gracefully and log failures for debugging. With the right approach, cron tasks can automate your plugin’s most important background processes reliably.