# jQuery Migrate: restoring removed jQuery APIs while the upgrade is under way

> jQuery Migrate loads after jQuery and restores removed APIs at runtime, logging a warning to the console for every deprecated call a page makes. It is a bridge tool, not a permanent dependency, and picking the wrong version pair or the wrong build file will leave you without the warnings you need.

**jquery/jquery-migrate** — A development tool to help migrate away from APIs and features that have been or will be removed from jQuery core

- Repository: https://github.com/jquery/jquery-migrate
- Stars: 2,093 · Forks: 477
- Language: JavaScript
- License: NOASSERTION
- Published: 2026-10-11 · Updated: 2026-10-11 · Language: en
- Canonical page: https://hysenlabs.com/projects/jquery-jquery-migrate

## Patching and warning at the same time: the mechanism behind jQuery Migrate

jQuery Migrate addresses a real tension in library upgrades: code that relied on old APIs breaks when those APIs disappear. It resolves this by adding the removed APIs back to the jQuery object while also logging a warning every time one is called. Pages keep running. Developers can see exactly what needs to change.

This dual behaviour is deliberate. A shim without warnings tells you nothing about the technical debt sitting in the codebase. Warnings without the shim just break pages. The README describes the purpose in clear terms: you keep the plugin until you no longer need it and can remove it. That sentence names the expectation directly. jQuery Migrate is meant to have a lifespan tied to a specific upgrade project, not to live in a codebase indefinitely.

Every message generated by the plugin starts with the string "JQMIGRATE", so searching the console for that prefix is enough to find everything the plugin detected. The full list of messages and the conditions that trigger each one lives in warnings.md at the repository root.

## Version pairing: jQuery 4.x needs Migrate 4.x, and upgrading from 1.x or 2.x requires a 3.x step

Migrate and jQuery versions must match by major version. The README's compatibility table assigns jQuery 1.x and 2.x to Migrate 1.x, jQuery 3.x to Migrate 3.x, and jQuery 4.x to Migrate 4.x. Using a mismatched pair is not a listed configuration.

A note at the top of the README adds a sequencing constraint for anyone still on jQuery 1.x or 2.x. Reaching jQuery 4.x requires passing through jQuery 3.x first, using Migrate 3.x for that intermediate step, before moving to jQuery 4.x with Migrate 4.x. The README links to the 3.x-stable branch and its README for guidance on that phase.

Version 4.0.2 is the latest on the 4.x line, published on 2026-01-21, and 3.6.0 covers the 3.x line, published on 2025-12-11. Browser support follows the same pairing: each Migrate version covers the same browsers as the jQuery version it accompanies, and the jQuery Browser Support page is the reference for that list.

## Loading the plugin in a web page and reading the first warnings

Usage starts with two script tags. jQuery comes first, and Migrate must follow it:

```html
<script src="https://code.jquery.com/jquery-4.0.0.js"></script>
<script src="https://code.jquery.com/jquery-migrate-4.0.2.js"></script>
```

Order matters. Loading Migrate before jQuery will not work, since it attaches itself to the `jQuery` object that must already exist.

With both files loaded, opening the browser's developer console shows a JQMIGRATE message for each call to a removed or deprecated API. Programmatic access is through `jQuery.migrateMessages`, an array that collects each unique message string in the order it was first triggered. A given message appears in the array only once per page load regardless of how many times the same condition fires, unless `jQuery.migrateReset()` has been called to clear the array first.

## Six properties that control what gets logged and how

The plugin exposes several properties on the `jQuery` object. Each targets a specific aspect of the output.

`jQuery.migrateVersion` is a read-only string that reports which version of Migrate is loaded. This is the value to include when filing a bug.

`jQuery.migrateMute` suppresses console output when set to `true`, while the `jQuery.migrateMessages` array continues collecting entries. A test harness that wants to inspect which deprecated APIs a page calls without filling the console can use this property.

`jQuery.migrateTrace` controls whether stack traces accompany warnings. Setting it to `false` gives warning text without the accompanying call stack, which reduces noise when the same warning fires repeatedly.

`jQuery.migrateDeduplicateMessages` defaults to the behaviour where each warning appears once per load. Setting it to `false` produces one entry per occurrence. The README notes this can generate substantial output when a deprecated call is inside a loop.

`jQuery.migrateReset()` clears the messages array and resets the plugin's memory of which warnings have already been seen, so a subsequent interaction starts recording from a clean state.

## Patch codes, selective disabling, and the warnings that have no code

`jQuery.migrateDisablePatches` takes patch codes and turns off those specific patches. Each code appears in square brackets next to its warning description in warnings.md. Disabling a patch removes both the shim for that API and its warning, which is useful when you have already fixed a particular deprecated usage and no longer want it reported.

`jQuery.migrateIsPatchEnabled` takes a code and returns `true` if that patch is currently active, `false` otherwise. Test code can use this to verify that a patch is off before calling the underlying un-patched API.

A detail that a quick scan of the README would miss: `jQuery.migrateDisablePatches` appears twice in the API section. The first entry gives the full description, including how to find codes in warnings.md and the existence of patches without codes. The second entry, further down the same list, reads only "jQuery.migrateDisablePatches: Disables patches by their codes." That shorter line is a duplication; the earlier, longer entry is authoritative.

Some warnings have no code and cannot be disabled at all. These cover setup errors: using an incompatible version of jQuery with Migrate, or loading Migrate more than once on the same page.

One additional property appears in the API list. `jQuery.UNSAFE_restoreLegacyHtmlPrefilter` is listed as a deprecated alias for `jQuery.migrateEnablePatches( "self-closed-tags" )`. Its name signals that the patch touches HTML filtering behaviour with security implications.

## Why the production build is the wrong choice during an upgrade

The README is explicit about this. The production build is minified and does not generate console warnings. It only logs a message when it loads, or when it detects a hard error such as an incompatible jQuery version. For deprecated API calls, it is silent. The README says relying on this file for development or debugging "will make your life miserable."

This gap matters in practice because CDN-based workflows can reach for the minified URL out of habit. A project that loads `jquery-migrate-4.0.2.min.js` instead of `jquery-migrate-4.0.2.js` will see no JQMIGRATE messages and no entries in `jQuery.migrateMessages`. From the console, the migration appears complete when it is not.

A work-in-progress build is available at releases.jquery.com/git/jquery-migrate-git.js. It reflects the most recent commits, but the README says it may be unstable and is not recommended for production sites.

## Building from source and the ESM module layout

For teams who want to build or test the plugin themselves, the README gives four commands:

```sh
git clone git://github.com/jquery/jquery-migrate.git
cd jquery-migrate
npm install
npm run build
```

Running the test suite uses either `npm test` or `npm run test:server`. The second command starts a server and opens the test suite at http://localhost:3000/test/ in a browser.

The package.json sets `"type": "module"`, which means the project uses ES modules internally. The exports field points to separate entry files for different consumption contexts: a Node.js wrapper at dist-module/wrappers/jquery-migrate.node-module-wrapper.js, a module entry at dist-module/jquery-migrate.module.js, and a bundler-specific require wrapper at dist/wrappers/jquery-migrate.bundler-require-wrapper.js. For plain browser use, the HTML script tag approach from the README bypasses all of that.

The package.json field reads `"license": "MIT"`, but GitHub classifies the repository as "Other" because it cannot parse LICENSE.txt; that file at the repository root holds the actual terms before redistribution.

## Conclusion

jQuery Migrate is the right choice for teams with a working jQuery 1.x, 2.x or 3.x codebase that needs to move to a newer version without rewriting everything first. A project already on jQuery 4.x with no deprecated API calls has no need for it. Before adding it, confirm the version pair from the README table: jQuery 4.x requires Migrate 4.x, and a codebase on jQuery 1.x or 2.x must pass through 3.x first. Then verify you are loading the development build, not the minified file, which produces no deprecation output. After the JQMIGRATE messages clear from the console, remove the plugin entirely.

## FAQ

### What does jQuery Migrate do?

It restores jQuery APIs that were removed from jQuery core and logs a warning to the browser console for each call to one of them. The purpose is to keep a page running on a newer jQuery version while a developer identifies and fixes each deprecated usage.

### Which version of jQuery Migrate do I use with jQuery 4.x?

jQuery 4.x pairs with jQuery Migrate 4.x. If you are upgrading from jQuery 1.x or 2.x, you must first upgrade to jQuery 3.x using jQuery Migrate 3.x before moving to jQuery 4.x.

### How do I see the deprecation warnings in jQuery Migrate?

Load the unminified development build after your jQuery script tag and open the browser developer console. Every warning starts with "JQMIGRATE". The production build is minified and produces no deprecation output.

### Can I disable specific jQuery Migrate patches?

Yes, using jQuery.migrateDisablePatches with the patch code. Codes appear in square brackets next to each warning in warnings.md. Some setup-related warnings have no code and cannot be disabled.

### Should jQuery Migrate stay in a production site?

No. The README frames it as a temporary tool: you use it until the JQMIGRATE warnings are gone, then remove it. Leaving it in place means shipping a shim that patches over deprecated API calls rather than fixing them.

## Sources

- [Issues](https://github.com/jquery/jquery-migrate/issues)
- [jquery/jquery-migrate on GitHub](https://github.com/jquery/jquery-migrate)
- [README](https://github.com/jquery/jquery-migrate/blob/main/README.md)
- [Releases](https://github.com/jquery/jquery-migrate/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/jquery-jquery-migrate