Understanding WordPress Plugin Version and Dependency Requirements

When you install a WordPress plugin, its version details answer two questions: which release you are installing and whether your site meets the plugin’s requirements. A plugin may require a minimum WordPress version and a minimum PHP version. It may also require other plugins to be installed.

WordPress uses some fields to decide whether it can activate a plugin. Other fields, such as the WordPress version the developer tested, report testing but do not set an upper limit. Knowing what each field means helps you understand why WordPress blocks activation and assess compatibility.

What each version field tells you

A plugin’s Version field identifies that plugin’s release. It does not state which WordPress or PHP versions the release supports. The Plugin Handbook’s header requirements describe the fields used in a plugin’s main PHP file.

The main requirement fields answer separate questions:

A plugin version’s text does not always show how WordPress will sort it. WordPress compares plugin versions with PHP’s version_compare() function; the Handbook notes, for example, that 1.02 compares as newer than 1.1. When checking release notes or comparing versions, use the plugin’s stated release history rather than relying only on visual comparison.

Where WordPress reads the requirements

For WordPress 5.8 and later, WordPress reads Requires at least and Requires PHP from the plugin’s main PHP file. WordPress starts reading the plugin’s code from that file. The readme.txt file supplies directory information, including Tested up to and Stable tag, but it is not the source WordPress parses for those minimum requirements in these versions. The readme documentation explains the distinction.

If the directory listing shows different requirements from an installed plugin, inspect the main PHP file’s header to confirm the WordPress and PHP minimums WordPress will check. The directory listing remains useful for testing information and release details. Plugin developers should keep public information consistent so users do not have to reconcile conflicting values.

How to judge compatibility

Start by comparing your site’s WordPress version with Requires at least and the server’s PHP version with Requires PHP. If either falls below the plugin’s declared minimum, resolve that mismatch before trying to activate the plugin.

Then use Tested up to to see which WordPress version the developer reports testing. A value below your WordPress version means the listing reports no testing against that newer version, leaving the plugin’s compatibility unconfirmed. A value at or above your version still does not guarantee that every feature will work with your theme, other plugins, and server configuration.

WordPress has its own server requirements and compatibility information. These describe WordPress core, not the PHP versions each plugin supports. Check the plugin’s declared minimum and its release notes separately. If a feature depends on an external service, a server extension, or another requirement that the headers do not describe, consult the plugin’s documentation.

What Requires Plugins handles

WordPress 6.5 introduced the Requires Plugins header for declaring plugin dependencies. A dependency is another plugin that a plugin needs in order to work. The header lists comma-separated WordPress.org plugin slugs, the short names used in plugin directory listings. The WordPress 6.5 dependency announcement describes how WordPress uses this information.

WordPress uses the declaration to guide installation and activation. WordPress blocks activation of a plugin while a listed dependency is inactive. It also prevents users from deactivating or deleting a dependency while an installed plugin relies on it. If a dependency disappears through a file transfer or deployment, WordPress displays a notice rather than automatically deactivating the dependent plugin.

The declaration has limits. It does not specify a minimum or maximum version for a dependency, and it does not guarantee that WordPress loads one plugin before another. If a plugin needs a feature introduced in a particular release of another plugin, its developer must handle that version-sensitive requirement in code or documentation. When a feature fails despite both plugins being active, check the dependency’s installed version and the dependent plugin’s release notes.

Diagnosing a requirement or dependency problem

If WordPress blocks activation, read the message and compare the stated requirement with your site’s WordPress or PHP version. WordPress provides a requirement-validation function. It checks declared WordPress and PHP requirements, as well as plugin dependency requirements.

If WordPress allows activation but a feature does not work, the metadata has not proved that the feature is compatible. Confirm that each named dependency is active, then check whether the plugin documentation specifies a dependency version or API requirement. An API is a set of functions and interfaces that lets other code use a plugin’s features. The dependency declaration alone does not describe which API versions the plugin needs.

When you install plugins with WP-CLI, check how it handles their requirements. WP-CLI documents a --with-dependencies option for installing dependencies named in Requires Plugins, as well as --ignore-requirements for bypassing WordPress or PHP checks. Choose the WP-CLI install options carefully. Ignoring requirements can let an incompatible plugin install, but it does not make the plugin compatible.

What I'm building

Delegate tasks. Get software.

Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.

Take a look at vroni.com