A WordPress plugin can contain thousands of lines of code, but WordPress still needs a small block of metadata in the main PHP file before it can identify the plugin correctly. That block is the plugin header.
The header looks simple enough to copy from another project, which is exactly why mistakes persist. Old boilerplates omit modern fields, minimum versions get copied without testing, dependency declarations are confused with runtime compatibility checks, and private plugins sometimes leave update behavior ambiguous.
This guide explains what the important fields actually mean, which ones WordPress uses for requirement validation, how plugin dependencies work, and how to verify the result before shipping. You can also use the WPToolix WordPress Plugin Header Generator to build the header while you follow along.
What is a WordPress plugin header?
A plugin header is a specially formatted PHP comment in the plugin’s main file. WordPress parses it to retrieve metadata such as the plugin name, version, author, minimum WordPress version, minimum PHP version and declared dependencies.
According to the official Plugin Handbook, Plugin Name is the only minimum field. In a real maintained plugin, however, additional metadata makes updates, compatibility decisions, translations and administration much clearer.
Only the main plugin file should carry the plugin header. Adding similar headers to several PHP files does not make a multi-file plugin more complete; it makes the plugin structure ambiguous.
The core plugin header fields worth understanding
Plugin Name
This is the human-readable name shown on the Plugins screen. Make it specific enough that an administrator can recognize the plugin without opening its files.
Description
The description appears in the WordPress admin plugin list. The Plugin Handbook recommends keeping it under 140 characters. Treat it as an operational description, not a marketing paragraph: say what the plugin does and avoid stuffing it with keywords.
Version
The Version field identifies the release currently installed. Increment it when you release code changes. Version strings also matter to update systems and to your own migration logic, so use a predictable versioning scheme rather than changing formats between releases.
Requires at least
This declares the lowest WordPress version that the plugin is designed to work with. It should reflect the WordPress APIs and behavior your plugin actually needs.
A common mistake is to set this to an unnecessarily old release because an older number appears to promise a larger market. If you do not test those versions, the field becomes misleading. Conversely, raising it to the newest WordPress release without a technical reason can exclude otherwise compatible sites.
Requires PHP
This is the minimum PHP version your plugin requires. WordPress core can use this metadata when validating whether plugin requirements are satisfied.
Choose the value from your code and test matrix. Typed properties, language syntax, library requirements and dependency packages can all raise the real PHP minimum. If you are planning a site-wide PHP upgrade rather than authoring a plugin, the WordPress PHP Requirements Checker provides a separate planning check.
How WordPress validates plugin requirements
WordPress has a core validate_plugin_requirements() function that validates requirements using metadata from the main plugin file. Current core documentation identifies Requires at least, Requires PHP and Requires Plugins as inputs to that validation.
This distinction matters because requirement metadata is not merely documentation for humans. WordPress can act on it. But a passing metadata check still does not prove that every plugin feature will work correctly on a particular hosting stack.
For example, a plugin can satisfy its declared PHP minimum and still fail because an expected PHP extension is absent, a third-party API changed, another plugin causes a conflict, or a specific workflow was never tested. Header requirements are the first compatibility gate, not the final QA process.
Requires Plugins: native plugin dependencies
WordPress introduced the Requires Plugins header with the Plugin Dependencies feature in WordPress 6.5. The value is a comma-separated list of WordPress.org-style plugin slugs.
For example, if an extension depends on WooCommerce, its dependency list can include the woocommerce slug. Do not enter a plugin file path such as woocommerce/woocommerce.php; core documentation specifically describes the field in terms of slugs.
When dependencies are declared, WordPress can prevent a dependent plugin from being activated until its dependencies are active. It also protects dependency plugins from normal deactivation or deletion while active dependents require them.
What Requires Plugins does not solve
The dependency header is intentionally narrower than Composer-style dependency management. Current WordPress core guidance notes important limitations: it does not express minimum or maximum versions for dependency plugins, and it does not guarantee plugin loading order.
That means an add-on requiring a particular class, function or API version may still need defensive checks such as class_exists(), function_exists() or an explicit version comparison at the point where that functionality matters.
Also be careful with distribution context. WordPress.org-hosted dependent plugins are expected to declare WordPress.org-hosted dependencies. Private and third-party distribution has different installation implications, because WordPress cannot necessarily offer an installation link for a dependency it cannot retrieve.
Update URI and private plugins
The Update URI header is particularly useful when you distribute a plugin outside the WordPress.org Plugin Directory. Its purpose is to help distinguish the plugin’s update source and avoid an unrelated directory plugin with a similar identity accidentally replacing it.
Do not treat Update URI as a complete updater. A custom plugin still needs an intentional update strategy if you want automatic updates from your own infrastructure. The header identifies metadata; it does not magically provide a release API.
Text Domain and Domain Path
The Text Domain identifies the translation domain used by translatable strings in the plugin. For a WordPress.org plugin, keep naming consistent with the plugin slug. Consistency makes translation calls easier to audit and avoids subtle localization failures.
Domain Path tells WordPress where translation files live when they are stored in a dedicated location such as /languages. Do not add fields simply because a boilerplate contains them; make them describe the structure you actually ship.
Licensing fields
The header can include License and License URI. WordPress itself uses the GPL, and the official Plugin Handbook recommends clearly indicating a plugin’s license. Plugins submitted to WordPress.org must use a GPL-compatible license.
Licensing also applies to bundled assets and third-party libraries. A correct header cannot repair incompatible licensing elsewhere in the package, so audit dependencies, images, fonts and copied code before distribution.
Do requirements belong in readme.txt too?
A useful readme is still important for installation instructions, changelogs and user-facing documentation. However, WordPress.org documentation notes that since WordPress 5.8, plugin readme files are not the source used to parse the plugin’s runtime requirements. Fields such as Requires PHP and Requires at least need to be correct in the main PHP file.
For a directory release, keep the readme and plugin header consistent so users do not see contradictory information, but consider the main PHP header authoritative for the requirements WordPress evaluates.
A practical workflow before releasing a plugin
- Generate or review the header. Start with the Plugin Header Generator, then remove fields your project does not use.
- Derive minimum versions from code. Check PHP syntax, Composer packages and WordPress APIs rather than guessing.
- Test the minimums you claim. A requirement you never test is only an assumption.
- Test the current supported stack too. Minimum-version testing catches one class of problems; current WordPress/PHP testing catches another.
- Verify dependencies. Test activation with dependencies present, inactive and missing. If you require a specific dependency version, test that separately because the header does not encode it.
- Check updates and rollback. Private plugins need a deliberate update strategy. Directory plugins should increment versions for releases.
- Review logs. Exercise important workflows with debugging enabled on staging and inspect warnings or deprecations with the WordPress Debug Log Analyzer.
Common plugin header mistakes
Copying old requirements: a five-year-old boilerplate can silently make your compatibility statement meaningless.
Using a plugin path in Requires Plugins: use the dependency slug expected by WordPress, not plugin-folder/plugin.php.
Assuming dependency declarations replace runtime checks: they do not provide dependency version constraints or loading-order guarantees.
Claiming compatibility too broadly: the lowest possible number is not automatically the best requirement. Support what you can realistically test and maintain.
Putting requirements only in readme.txt: modern WordPress reads the relevant requirement headers from the main PHP plugin file.
Treating the header as the whole release checklist: security, sanitization, escaping, capabilities, database migrations, uninstall behavior, licensing and regression testing all live beyond this metadata block.
How to verify the finished plugin
Install the plugin on a staging site and open Plugins in wp-admin. Confirm that the displayed name, description, author, version and dependency information match what you intended. Then test activation against the lowest supported WordPress and PHP versions, followed by a current supported environment.
If the plugin schedules recurring work, verify the events rather than assuming registration succeeded; the WordPress Cron Generator explains the duplicate guard and cleanup pattern. If a failure occurs, capture the actual log instead of repeatedly changing requirements until the error disappears.
Final checklist
- One plugin header in the main PHP file.
- Clear Plugin Name and short Description.
- Release Version updated intentionally.
- Requires at least and Requires PHP backed by testing.
- Requires Plugins uses comma-separated slugs where appropriate.
- Dependency versions checked separately when necessary.
- Update URI considered for non-directory distribution.
- Text Domain, Domain Path and license fields match the package.
- Readme documentation agrees with the main header.
- Activation, critical workflows and logs verified on staging.
A good plugin header is small, but it is part of the plugin’s compatibility contract. Keep it accurate, test what it claims, and update it as deliberately as the code it describes.