How to Remove jQuery Migrate Safely in WordPress

Customization

December 29, 2025

How to Remove jQuery Migrate Safely in WordPress

WordPress still loads jquery-migrate by default for backward compatibility.
While useful for legacy scripts, it often adds unnecessary JavaScript payload and can
mask deprecated jQuery usage in themes or plugins.

If your site targets modern browsers and uses up-to-date code,
removing jQuery Migrate can improve performance and help you detect outdated dependencies.
This article explains how to remove it safely without breaking your site.

What Is jQuery Migrate?

jQuery Migrate is a compatibility layer that restores deprecated jQuery APIs
removed in newer jQuery versions.
WordPress includes it to prevent older themes and plugins from breaking.

However:

It adds extra JS (download + parse + execute)
It hides deprecated usage that should be fixed
Most modern themes/plugins no longer need it

Important: When You Should NOT Remove It

Do not remove jQuery Migrate if:

You rely on old plugins that haven’t been updated in years
You see console warnings/errors when it’s removed
You cannot test thoroughly (front-end + admin)

Always test on staging first.

How WordPress Loads jQuery Migrate

WordPress registers jQuery like this (simplified):

jquery → depends on jquery-core and jquery-migrate

To remove Migrate safely, you must modify the dependency list,
not deregister jQuery entirely.

Recommended Approach: Remove jQuery Migrate on the Front End Only

Never remove it in the admin area.
The block editor and some admin screens may still rely on legacy behavior.

Safe Front-End Removal

<?php
add_action( 'wp_default_scripts', function ( $scripts ) {
  if ( is_admin() ) {
    return;
  }

  if ( isset( $scripts->registered['jquery'] ) ) {
    $deps = $scripts->registered['jquery']->deps;

    // Remove jquery-migrate from jQuery dependencies
    $scripts->registered['jquery']->deps = array_diff( $deps, array( 'jquery-migrate' ) );
  }
} );

Why this is safe:

Core jQuery stays intact
Only the dependency is removed
Admin/editor remains untouched

Do NOT Use wp_deregister_script( ‘jquery-migrate’ )

Directly deregistering jQuery Migrate can break dependencies unexpectedly.
Other scripts may still declare it as required.

Adjusting dependencies is the correct approach.

How to Detect Whether You Still Need jQuery Migrate

Enable Migrate Debug Mode

Before removing it, let jQuery Migrate warn you about deprecated usage.

<?php
define( 'JQUERY_MIGRATE_LOG', true );

Then check the browser console for warnings.
If you see messages like:

jQuery.fn.live() is deprecated
jQuery.browser is deprecated

You still have legacy code that should be updated.

Common Breakage Patterns

If something breaks after removal, it’s usually due to:

Old event APIs (.live(), .bind())
Removed properties (jQuery.browser)
Implicit $(document).ready() assumptions

Fixing these in your theme is better than keeping Migrate forever.

What About Plugins?

If a plugin depends on jQuery Migrate:

Check for updates (many plugins have fixed this)
Consider replacing the plugin
As a last resort, conditionally keep Migrate on pages where it’s required

Conditional Keep (Advanced)

<?php
add_action( 'wp_default_scripts', function ( $scripts ) {
  if ( is_admin() ) {
    return;
  }

  // Example: keep migrate on a specific page
  if ( is_page( 123 ) ) {
    return;
  }

  if ( isset( $scripts->registered['jquery'] ) ) {
    $scripts->registered['jquery']->deps = array_diff(
      $scripts->registered['jquery']->deps,
      array( 'jquery-migrate' )
    );
  }
} );