Title: wp_unschedule_hook
Published: November 20, 2017
Last modified: February 24, 2026

---

# wp_unschedule_hook( string $hook, bool $wp_error = false ): int|false|󠀁[WP_Error](https://developer.wordpress.org/reference/classes/wp_error/)󠁿

## In this article

 * [Description](https://developer.wordpress.org/reference/functions/wp_unschedule_hook/?output_format=md#description)
 * [Parameters](https://developer.wordpress.org/reference/functions/wp_unschedule_hook/?output_format=md#parameters)
 * [Return](https://developer.wordpress.org/reference/functions/wp_unschedule_hook/?output_format=md#return)
 * [Source](https://developer.wordpress.org/reference/functions/wp_unschedule_hook/?output_format=md#source)
 * [Hooks](https://developer.wordpress.org/reference/functions/wp_unschedule_hook/?output_format=md#hooks)
 * [Related](https://developer.wordpress.org/reference/functions/wp_unschedule_hook/?output_format=md#related)
 * [Changelog](https://developer.wordpress.org/reference/functions/wp_unschedule_hook/?output_format=md#changelog)

[ Back to top](https://developer.wordpress.org/reference/functions/wp_unschedule_hook/?output_format=md#wp--skip-link--target)

Unschedules all events attached to the hook.

## 󠀁[Description](https://developer.wordpress.org/reference/functions/wp_unschedule_hook/?output_format=md#description)󠁿

Can be useful for plugins when deactivating to clean up the cron queue.

Warning: This function may return boolean false, but may also return a non-boolean
value which evaluates to false. For information about casting to booleans see the
[ PHP documentation](https://www.php.net/manual/en/language.types.boolean.php/).
Use the `===` operator for testing the return value of this function.

## 󠀁[Parameters](https://developer.wordpress.org/reference/functions/wp_unschedule_hook/?output_format=md#parameters)󠁿

 `$hook`stringrequired

Action hook, the execution of which will be unscheduled.

`$wp_error`booloptional

Whether to return a [WP_Error](https://developer.wordpress.org/reference/classes/wp_error/)
on failure.

Default:`false`

## 󠀁[Return](https://developer.wordpress.org/reference/functions/wp_unschedule_hook/?output_format=md#return)󠁿

 int|false|[WP_Error](https://developer.wordpress.org/reference/classes/wp_error/)
On success an integer indicating number of events unscheduled (0 indicates no events
were registered on the hook), false or [WP_Error](https://developer.wordpress.org/reference/classes/wp_error/)
if unscheduling fails.

## 󠀁[Source](https://developer.wordpress.org/reference/functions/wp_unschedule_hook/?output_format=md#source)󠁿

    ```php
    function wp_unschedule_hook( $hook, $wp_error = false ) {
    	/**
    	 * Filter to override clearing all events attached to the hook.
    	 *
    	 * Returning a non-null value will short-circuit the normal unscheduling
    	 * process, causing the function to return the filtered value instead.
    	 *
    	 * For plugins replacing wp-cron, return the number of events successfully
    	 * unscheduled (zero if no events were registered with the hook). If unscheduling
    	 * one or more events fails then return either a WP_Error object or false depending
    	 * on the value of the `$wp_error` parameter.
    	 *
    	 * @since 5.1.0
    	 * @since 5.7.0 The `$wp_error` parameter was added, and a `WP_Error` object can now be returned.
    	 *
    	 * @param null|int|false|WP_Error $pre      Value to return instead. Default null to continue unscheduling the hook.
    	 * @param string                  $hook     Action hook, the execution of which will be unscheduled.
    	 * @param bool                    $wp_error Whether to return a WP_Error on failure.
    	 */
    	$pre = apply_filters( 'pre_unschedule_hook', null, $hook, $wp_error );

    	if ( null !== $pre ) {
    		if ( $wp_error && false === $pre ) {
    			return new WP_Error(
    				'pre_unschedule_hook_false',
    				__( 'A plugin prevented the hook from being cleared.' )
    			);
    		}

    		if ( ! $wp_error && is_wp_error( $pre ) ) {
    			return false;
    		}

    		return $pre;
    	}

    	$crons = _get_cron_array();
    	if ( empty( $crons ) ) {
    		return 0;
    	}

    	$results = array();

    	foreach ( $crons as $timestamp => $args ) {
    		if ( ! empty( $crons[ $timestamp ][ $hook ] ) ) {
    			$results[] = count( $crons[ $timestamp ][ $hook ] );
    		}

    		unset( $crons[ $timestamp ][ $hook ] );

    		if ( empty( $crons[ $timestamp ] ) ) {
    			unset( $crons[ $timestamp ] );
    		}
    	}

    	/*
    	 * If the results are empty (zero events to unschedule), no attempt
    	 * to update the cron array is required.
    	 */
    	if ( empty( $results ) ) {
    		return 0;
    	}

    	$set = _set_cron_array( $crons, $wp_error );

    	if ( true === $set ) {
    		return array_sum( $results );
    	}

    	return $set;
    }
    ```

[View all references](https://developer.wordpress.org/reference/files/wp-includes/cron.php/)
[View on Trac](https://core.trac.wordpress.org/browser/tags/6.9.4/src/wp-includes/cron.php#L654)
[View on GitHub](https://github.com/WordPress/wordpress-develop/blob/6.9.4/src/wp-includes/cron.php#L654-L724)

## 󠀁[Hooks](https://developer.wordpress.org/reference/functions/wp_unschedule_hook/?output_format=md#hooks)󠁿

 [apply_filters( ‘pre_unschedule_hook’, null|int|false|WP_Error $pre, string $hook, bool $wp_error )](https://developer.wordpress.org/reference/hooks/pre_unschedule_hook/)

Filter to override clearing all events attached to the hook.

## 󠀁[Related](https://developer.wordpress.org/reference/functions/wp_unschedule_hook/?output_format=md#related)󠁿

| Uses | Description | 
| [_get_cron_array()](https://developer.wordpress.org/reference/functions/_get_cron_array/)`wp-includes/cron.php` |

Retrieves cron info array option.

  | 
| [_set_cron_array()](https://developer.wordpress.org/reference/functions/_set_cron_array/)`wp-includes/cron.php` |

Updates the cron option with the new cron array.

  | 
| [__()](https://developer.wordpress.org/reference/functions/__/)`wp-includes/l10n.php` |

Retrieves the translation of $text.

  | 
| [apply_filters()](https://developer.wordpress.org/reference/functions/apply_filters/)`wp-includes/plugin.php` |

Calls the callback functions that have been added to a filter hook.

  | 
| [is_wp_error()](https://developer.wordpress.org/reference/functions/is_wp_error/)`wp-includes/load.php` |

Checks whether the given variable is a WordPress Error.

  | 
| [WP_Error::__construct()](https://developer.wordpress.org/reference/classes/wp_error/__construct/)`wp-includes/class-wp-error.php` |

Initializes the error.

  |

[Show 4 more](https://developer.wordpress.org/reference/functions/wp_unschedule_hook/?output_format=md#)
[Show less](https://developer.wordpress.org/reference/functions/wp_unschedule_hook/?output_format=md#)

| Used by | Description | 
| [wp_install()](https://developer.wordpress.org/reference/functions/wp_install/)`wp-admin/includes/upgrade.php` |

Installs the site.

  |

## 󠀁[Changelog](https://developer.wordpress.org/reference/functions/wp_unschedule_hook/?output_format=md#changelog)󠁿

| Version | Description | 
| [5.7.0](https://developer.wordpress.org/reference/since/5.7.0/) | The `$wp_error` parameter was added. | 
| [5.1.0](https://developer.wordpress.org/reference/since/5.1.0/) | Return value added to indicate success or failure. | 
| [4.9.0](https://developer.wordpress.org/reference/since/4.9.0/) | Introduced. |

## User Contributed Notes

You must [log in](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_unschedule_hook%2F)
before being able to contribute a note or feedback.