wppaste
WordPress

remove_action( string $hook_name, callable|string|array $callback, int $priority = 10 ): bool

Since
1.2.0
Source
wp-includes/plugin.php:622

Detaches a specific callback from an action hook by hook name, callback, and priority, the same three values used when the callback was originally attached. It works by calling remove_filter() under the hood, since WordPress stores actions and filters in the same hook structure. The priority must match exactly or the removal silently fails with no warning, which is the most common source of confusion when using it.

Removes a callback function from an action hook.

Description

This can be used to remove default functions attached to a specific action hook and possibly replace them with a substitute.

To remove a hook, the $callback and $priority arguments must match when the hook was added. This goes for both filters and actions. No warning will be given on removal failure.

Compatibility

WordPress
since 1.2.0
PHP
7.4–8.6-dev
  • 6.7.7
  • 6.8.8
  • 6.9.7
  • 7.0.4
  • 7.1.0

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

Parameters

$hook_namestring
The action hook to which the function to be removed is hooked.
$callbackcallable|string|array
The name of the function which should be removed.
This function can be called unconditionally to speculatively remove a callback that may or may not exist.
$priorityintoptional
The exact priority used when adding the original action callback. Default 10.Default: 10

Return value

bool
Whether the function is removed.

Code examples

Every example is editable and runs in a real WordPress booted in your browser by WordPress Playground. Press Run, then edit the code: clicking away re-runs it. Nothing is sent anywhere until you do.

WordPress attaches the core feed_links() function to wp_head at priority 2 by default, so remove it and confirm the output no longer includes the feed link markup.

remove_action( 'wp_head', 'feed_links', 2 );

ob_start();
do_action( 'wp_head' );
$head_output = ob_get_clean();

if ( false === strpos( $head_output, 'alternate' ) ) {
	echo esc_html( 'feed_links output was successfully removed from wp_head.' );
} else {
	echo esc_html( 'feed_links still ran, removal did not match.' );
}

The priority argument (2) has to match the priority WordPress used when it originally hooked feed_links onto wp_head, otherwise nothing is removed.

Check whether remove_action actually found and removed a callback

Attach a custom callback at priority 20 on a fictional hook, then try removing it with the wrong priority before the right one to see how the return value behaves.

function acme_log_price_change() {
	echo esc_html( 'Price change logged.' );
}

add_action( 'acme_price_updated', 'acme_log_price_change', 20 );

$removed_with_wrong_priority = remove_action( 'acme_price_updated', 'acme_log_price_change', 10 );
$removed_with_right_priority = remove_action( 'acme_price_updated', 'acme_log_price_change', 20 );

printf(
	'Wrong priority removal returned: %s. Right priority removal returned: %s.',
	esc_html( $removed_with_wrong_priority ? 'true' : 'false' ),
	esc_html( $removed_with_right_priority ? 'true' : 'false' )
);

Common problems and fixes · 3

Why doesn't remove_action() remove the callback I'm targeting?

The most common cause is a mismatched priority. remove_action() only removes a callback if the hook name, callback, and priority all match exactly what was used in the original add_action() call, and no warning is given when the match fails.

Why does my remove_action() call have no effect even though I'm sure the callback matches?

It probably runs too late. Since remove_action() just tells the hook system to drop an entry from its list, it has no effect on a callback that has already executed for a do_action() call that already fired earlier in the request.

How do I remove an action that was added as a class method?

When the original $callback is an array like array( $instance, 'method_name' ), remove_action() needs the exact same object instance (or class name for static methods) to find a match, per the callable|string|array type this parameter accepts.

Alternatives and related functions

add_action
When you want to attach a new callback instead of detaching an existing one, including re-adding a replacement after removing the default.
remove_filter
When the underlying function you actually want to call directly is being documented or debugged, since remove_action() is just a wrapper around it.
remove_all_actions
When you need to strip every callback from a hook regardless of priority, rather than removing one specific callback.
has_action
When you need to check whether a callback is currently attached to a hook before deciding whether to remove it.

Performance profile

How much work a call to remove_action() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class
Trivial

Touches nothing outside its own arguments.

Scaling
Constant

No loop in the body: the same number of instructions runs whatever you pass in.

Instructions
9

Executed per call on PHP 8.5. The body compiles to 9.

Plugin surface
None

Nothing here hands control to plugin code.

Called by
33

33 places in core call this, so the cost is paid more often than your own code shows.

What one call costs · 1 distinct outcome

One number would be a lie: the work depends on which branch runs. These are every distinct cost remove_action() can have, taken from its control-flow graph on PHP 8.5.

WhenInstructionsCalls it makes
always9remove_filter()

Across PHP versions

Compiles the same on PHP 7.4, 8.1, 8.2, 8.3, 8.4, 8.5 and 8.6-dev: 9 instructions, 9 executed per call, 0 branches. The work does not change between versions.

An instruction is not a fixed amount of time, so a matching count is not necessarily the same speed; what it rules out is a difference in the work itself.

Uses · 1

Used by · 33

Show all 33

Source code

View on Trac View on GitHub 

function remove_action( $hook_name, $callback, $priority = 10 ) {	return remove_filter( $hook_name, $callback, $priority );}

Changelog

Introduced in 1.2.0. Unchanged from 6.7.7 through 7.1.0.

  1. 6.7.7
  2. 6.8.8
  3. 6.9.7
  4. 7.0.4
  5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data
Generated from the wordpress-develop 7.0.4 tag, from src/wp-includes/plugin.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.
Corrections
Something wrong on this page? Report it and it gets fixed in the next regeneration.