WordPress Plugin Dependency Checks in 2026: Dependency Checks, Self-Deactivation, and Admin Notices

Plugins often depend on other plugins. The most common example is a WooCommerce add-on that assumes WooCommerce classes and functions exist. The failure mode is predictable. If the dependency is missing or outdated, the add-on may trigger fatal errors or spam the admin with warnings, especially during activation. A “current standard” approach in 2026 uses two layers:

• WordPress-level dependency declaration (so WordPress can block obvious bad activations)
• Your own minimum version guard (because WordPress does not enforce dependency versions)

What changed since older tutorials

WordPress 6.5 introduced Plugin Dependencies and a new plugin header field called “Requires Plugins.” WordPress reads this header and can prevent activating a plugin if required plugins are not installed and active. This is useful, but it does not solve minimum version requirements. WordPress dependency handling focuses on presence and activation state, not “WooCommerce must be at least X.Y.Z.”

The goal

When the dependency is missing or below the minimum version, the plugin should:

• Abort activation cleanly
• Deactivate itself (if it was activated)
• Show a clear admin notice with the minimum version required and a link back to the Plugins screen

Step 1: Declare the dependency in the plugin header (WordPress 6.5+)

Add “Requires Plugins” to your main plugin file header. WordPress uses it to manage activation and dependency UI. Example:

<?php
/**
 * Plugin Name: My Woo Add-on
 * Version: 1.0.0
 * Requires at least: 6.0
 * Requires PHP: 7.4
 * Requires Plugins: woocommerce
 */

If you ship WooCommerce-specific extensions, also consider WooCommerce compatibility headers (informational, not enforcement):

/**
 * WC requires at least: 8.0
 * WC tested up to: 10.4
 */

Step 2: Build a minimum version check (WooCommerce example)

For WooCommerce add-ons, a common pattern is:

• First check that WooCommerce is active
• Then check the WooCommerce version

For activation-time checks, you can rely on WC_VERSION when WooCommerce is active. Many extensions use that constant because it is lightweight.

Step 3: Abort activation and self-deactivate safely

WordPress provides deactivate_plugins(), which is often used for self-deactivation when required features are missing. Also, register_activation_hook() must be registered in the main plugin file that WordPress activates, otherwise it will not fire the way you expect.

A smoother user experience than wp_die()

Many older examples call wp_die() directly. That works, but it is a hard stop and looks like an error screen. A more modern pattern is:

• Set a short-lived transient with the message
• Deactivate the plugin
• Let WordPress return the user to the Plugins page
• Render the notice there via admin_notices

Full example you can paste into a single-file plugin

Replace the constants and text domain to match your plugin.

<?php
/**
 * Plugin Name: My Woo Add-on
 * Description: Example dependency guard for WooCommerce.
 * Version: 1.0.0
 * Requires at least: 6.0
 * Requires PHP: 7.4
 * Requires Plugins: woocommerce
 */

defined( 'ABSPATH' ) || exit;

const MY_ADDON_MIN_WC       = '8.0.0';
const MY_ADDON_NOTICE_KEY   = 'my_addon_activation_notice';
const MY_ADDON_PLUGIN_NAME  = 'My Woo Add-on';

register_activation_hook( __FILE__, 'my_addon_on_activate' );

function my_addon_on_activate(): void {
    $problem = my_addon_get_dependency_problem();

    if ( $problem === '' ) {
        return;
    }

    // Store a message to show on the Plugins screen.
    set_transient( MY_ADDON_NOTICE_KEY, $problem, 60 );

    // Deactivate this plugin.
    require_once ABSPATH . 'wp-admin/includes/plugin.php';
    deactivate_plugins( plugin_basename( __FILE__ ) );

    // Prevent “Plugin activated” notice.
    if ( isset( $_GET['activate'] ) ) {
        unset( $_GET['activate'] );
    }
}

/**
 * Returns an empty string when requirements are satisfied,
 * otherwise returns a human-readable error message.
 */
function my_addon_get_dependency_problem(): string {
    // Dependency presence.
    if ( ! class_exists( 'WooCommerce' ) || ! defined( 'WC_VERSION' ) ) {
        return sprintf(
            '%s could not be activated because WooCommerce is not installed and active.',
            '<strong>' . esc_html( MY_ADDON_PLUGIN_NAME ) . '</strong>'
        );
    }

    // Minimum version requirement.
    if ( version_compare( WC_VERSION, MY_ADDON_MIN_WC, '<' ) ) {
        return sprintf(
            '%1$s requires WooCommerce %2$s or higher. Current version: %3$s.',
            '<strong>' . esc_html( MY_ADDON_PLUGIN_NAME ) . '</strong>',
            esc_html( MY_ADDON_MIN_WC ),
            esc_html( WC_VERSION )
        );
    }

    return '';
}

add_action( 'admin_notices', 'my_addon_render_activation_notice' );

function my_addon_render_activation_notice(): void {
    if ( ! current_user_can( 'activate_plugins' ) ) {
        return;
    }

    $message = get_transient( MY_ADDON_NOTICE_KEY );
    if ( ! $message ) {
        return;
    }

    delete_transient( MY_ADDON_NOTICE_KEY );

    $plugins_url = admin_url( 'plugins.php' );

    printf(
        '<div class="notice notice-error"><p>%1$s %2$s</p></div>',
        wp_kses_post( $message ),
        '<a href="' . esc_url( $plugins_url ) . '">Return to Plugins</a>'
    );
}

Example admin notice screenshot

After adding the code above, you should see an admin notice like the following when the dependency is missing or below the minimum version.

Why this works well

• It prevents confusing fatal errors during activation.
• It uses WordPress’s built-in deactivation function, which is intended for dependency failures.
• It keeps the admin in a familiar place (the Plugins screen) with a clear next step.

Step 4: Add a runtime guard (recommended)

Even if activation is blocked correctly, dependencies can be deactivated later. This can happen during troubleshooting or after an update. A runtime guard prevents front-end breakage. For WooCommerce, it is common to attach WooCommerce-dependent initialization to a WooCommerce hook and bail out if the version is too low. Example idea:

• If WooCommerce is missing or too old, do not bootstrap your main plugin features.
• Show an admin notice explaining what needs to be updated.

Decision boundaries

Use activation blocking when your plugin cannot operate at all without the dependency. This is typical for WooCommerce add-ons. Use runtime guards even if you block activation. Dependencies can change after activation, and runtime guards reduce support issues and broken dashboards.

Wrapping up

In 2026, the best practice is to combine WordPress’s “Requires Plugins” header (for basic dependency enforcement) with your own minimum version checks (for real compatibility). That combination avoids fatal errors, keeps admins informed, and makes your plugin behave predictably in real-world environments.