Developer · Guide
How to Manage WordPress With Composer

Short answer
To manage WordPress with Composer, install Composer, add a composer.json file in the project root, and list WordPress core, plugins, themes, and PHP libraries as required packages. Run composer install to match the lock file, composer update to move to newer versions, and commit composer.lock to Git so every machine installs the same code.
Key takeaways
- Composer is a per-project dependency manager for PHP, not a system-wide package manager.
- composer.json lists what you want, composer.lock records the exact versions installed.
- Packagist is the main Composer repository; WPackagist mirrors WordPress.org plugins and themes.
- Bedrock starts a Composer-managed WordPress site with core in web/wp and content in web/app.
- Keep vendor out of Git and run composer update on staging, never on the live site.
What is Composer and what does it do for WordPress?
Composer is a tool for dependency management in PHP that lets you list the libraries a project needs and then install and update them.
GetComposer.org states that Composer lets you declare the libraries your project depends on, and it will manage them for you (checked November 2026).
For WordPress, that means core, plugins, themes, and PHP libraries can all be listed in one file instead of downloaded by hand. When the list changes, one command brings the whole site in line with it.
Composer works per project, not for the whole machine. GetComposer.org states that Composer manages packages on a per-project basis, installing them in a directory such as vendor inside your project (checked November 2026).
A guide on how to create a WordPress plugin shows the plugin structure that Composer-managed code still follows, with a main PHP file and a header comment.
When should you manage WordPress with Composer?
Use Composer when more than one person works on a site, when you deploy from Git, or when a plugin or theme needs PHP libraries.
Composer fits custom builds, client sites with a set list of plugins, and teams that need the same code on every machine. It records exact versions, so a fresh checkout installs the same code that ran on the last deploy.
Composer is less useful for a simple site where the owner installs plugins from the dashboard and never touches code. The dashboard updater already handles that case, and adding Composer would add steps with no gain.
Use Composer for a theme or plugin you build when it needs a third-party library, such as a logging library or a PDF writer. The library then ships as a listed dependency instead of code pasted into your project.
A guide on how to deploy WordPress with GitHub Actions shows the deploy flow that pairs well with Composer, since the server can install dependencies from the lock file.
What do you need before you start?
You need PHP on your machine, command-line access, and a WordPress site or project folder to manage.
Composer in its latest version requires PHP 7.2.5 to run. GetComposer.org states that requirement, and that a long-term-support version 2.2.x still offers support for PHP 5.3.2 and later (checked November 2026).
WordPress itself needs a newer PHP version than Composer does. WordPress.org states that WordPress recommends PHP 8.3 or greater, with HTTPS support (checked November 2026).
You also need Git, because Composer-managed projects keep the list of dependencies in Git while the downloaded files stay out of it. The vendor folder is rebuilt from the list on each machine.
Set aside about 30 minutes for a first setup. Installing Composer takes a few minutes, and wiring the first project takes the rest.
How do you install Composer?
Install Composer once on your machine, then use the composer command in any project folder.
On Linux, Unix, or macOS, download the installer and run it, then move the result into a folder on your PATH. GetComposer.org gives this move command for a global install (checked November 2026):
mv composer.phar /usr/local/bin/composer
After that step, run composer instead of php composer.phar. If the move fails for want of rights, run it again with sudo, or use ~/.local/bin for a user-only install.
On Windows, download and run Composer-Setup.exe. GetComposer.org states that the installer sets up the latest Composer version and your PATH so you can call composer from any folder (checked November 2026).
Check the install with this command:
composer -V
A working install prints a version line, such as Composer version 2.4.0. If the command is not found, close the terminal, open a new one, and try again so the new PATH loads.
How do you set up composer.json for a WordPress site?
Create a composer.json file in the project root that names the project and lists what it needs.
All you need to start is a composer.json file. GetComposer.org states that this file describes the dependencies of your project, and that it should sit in the top-most folder of your project (checked November 2026).
The require key maps package names to version limits. GetComposer.org states that require takes an object that maps package names, such as monolog/monolog, to version constraints, such as 1.0.* (checked November 2026).
A version limit of 2.0.* means any version from 2.0 up to, but not including, 2.1. GetComposer.org states that 2.0.* means any version greater than or equal to 2.0 and less than 2.1 (checked November 2026).
For a full WordPress site, use a starter such as Bedrock. Roots.io gives this command to start a Bedrock project (checked November 2026):
composer create-project roots/bedrock my-site
Bedrock keeps WordPress core in web/wp, content in web/app, and settings in config/application.php. Roots.io states that its structure keeps sensitive files out of the web root, with core and plugins kept out of version control (checked November 2026).
How do you add WordPress core, plugins, and themes?
Add core, plugins, and themes as named packages, and tell Composer where each type of package should land.
By default Composer puts packages in vendor, which is wrong for plugins and themes. The composer/installers package plus an installer-paths block fixes that. Altis Docs states that you first install composer/installers, then set extra.installer-paths to place each type in the right folder (checked November 2026).
A paths block for a standard layout looks like this:
"extra": {
"installer-paths": {
"wp-content/plugins/{$name}/": ["type:wordpress-plugin"],
"wp-content/themes/{$name}/": ["type:wordpress-theme"]
}
}
Many WordPress.org plugins are not on Packagist, so add WordPress Packagist as a second source. Altis Docs states that plugins not on Packagist can be installed through a third-party Composer repository called WordPress Packagist (checked November 2026).
Add it under repositories in composer.json:
"repositories": [
{
"type": "composer",
"url": "https://wpackagist.org"
}
]
Then require a plugin by its WordPress.org slug. Altis Docs gives this example for Akismet, whose slug on WordPress.org is akismet (checked November 2026):
composer require wpackagist-plugin/akismet
Packagist.org is the main Composer repository, so packages listed there need no extra repository entry (checked November 2026).
| Package type | Example require | Where it lands |
|---|---|---|
| PHP library | composer require monolog/monolog | vendor/monolog/monolog |
| WordPress.org plugin | composer require wpackagist-plugin/akismet | wp-content/plugins/akismet |
| WordPress.org theme | composer require wpackagist-theme/neve | wp-content/themes/neve |
| WordPress core (Bedrock) | roots/wordpress in composer.json | web/wp |
| Must-use plugin | type:wordpress-muplugin path | web/app/mu-plugins |
How do you install, update, and lock dependencies?
Use install to match the lock file and update to move to newer versions, and commit the lock file to Git.
Run composer update the first time to resolve versions and write composer.lock. GetComposer.org states that update resolves all dependencies in composer.json, writes their exact versions to composer.lock, and then downloads them into vendor (checked November 2026).
Commit composer.lock to version control. GetComposer.org states that committing the lock file means everyone who sets up the project uses the exact same versions (checked November 2026).
After pulling new changes from Git, run composer install. GetComposer.org states that install uses the exact versions in composer.lock so the package versions stay the same for everyone on the project (checked November 2026).
To move to the newest versions that fit your limits, run composer update again. That command fetches the latest matching versions and writes the new versions into the lock file.
Update one package only by naming it:
composer update monolog/monolog
GetComposer.org states that you can list one dependency as an argument to install, upgrade, or remove just that dependency (checked November 2026).
Keep vendor out of Git. GetComposer.org advises adding vendor to .gitignore, since you do not want all that third-party code in your versioned repository (checked November 2026).
How do you use autoloading in a plugin or theme?
Load Composer's autoloader at the top of your plugin or theme, then use the classes it provides with no extra include calls.
For libraries that give autoload data, Composer builds a vendor/autoload.php file. GetComposer.org states that you can include this file and start using the classes those libraries provide with no extra work (checked November 2026).
Include it from your main plugin file:
require __DIR__ . '/vendor/autoload.php';
Add your own code to the autoloader with an autoload block in composer.json. GetComposer.org gives a PSR-4 example that maps the Acme namespace to a src folder, so src/Foo.php holds the Acme\Foo class (checked November 2026).
After you change the autoload block, run this command to rebuild the autoloader:
composer dump-autoload
GetComposer.org states that dump-autoload re-generates the vendor/autoload.php file after you add the autoload field (checked November 2026).
A guide on how to check a plugin for vulnerabilities is worth reading before you add a new library, since each dependency adds code you must trust.
What mistakes should you avoid?
Avoid committing the vendor folder, editing files inside it, and updating on the live site without a lock file.
Never edit code inside vendor. The next install or update will overwrite your change, and the fix will vanish without a trace in Git.
Do not commit vendor or node_modules to Git. They are rebuilt from composer.json and composer.lock, and they make the repository large and slow to clone.
Do not run composer update on the live site. Update on a local copy or staging first, check the site, commit the new lock file, and then run composer install on the server.
A guide on how to set up a staging site for WordPress shows how to check updates away from live visitors before you deploy them.
Do not skip the lock file. Without it, two machines can install different versions from the same composer.json, and a bug can appear on one machine only.
Do not use the dashboard updater and Composer for the same plugin. Pick one source of truth, or the two systems will overwrite each other and the lock file will lie about what is installed.
Frequently asked questions
Does every WordPress site need Composer?
No. A site that only uses the dashboard updater does not need Composer. Composer pays off when you deploy from Git, work in a team, or need PHP libraries in a theme or plugin.
What is the difference between composer.json and composer.lock?
composer.json lists the packages and version limits you want. composer.lock records the exact versions that were resolved, so every install after that uses the same code. Commit the lock file to Git.
Does Composer put plugins in wp-content/plugins by itself?
No. By default Composer installs packages into vendor, which is wrong for plugins and themes. Add composer/installers and an installer-paths block so wordpress-plugin packages land in wp-content/plugins and wordpress-theme packages land in wp-content/themes.
How do I update safely on a live site?
Run composer update on a local copy or staging site first, check the site, commit the new lock file, then run composer install on the server. Never run update on the live site, since it can pull versions you have not checked.
Can I install a WordPress.org plugin with Composer?
Yes, with the composer require command. For WordPress.org plugins, add the WPackagist repository and require wpackagist-plugin followed by the plugin slug, such as wpackagist-plugin/akismet.
Can I edit code inside the vendor folder?
Never edit files inside vendor, since the next install or update overwrites them. Fix the code in its own package or fork it, then require your fixed version from composer.json instead.
Sources
- Introduction Composer
- Basic usage Composer
- Bedrock: WordPress with Composer and Git Roots
- Third-Party Plugins Altis
- Packagist Packagist
- Requirements WordPress.org
Is your product missing, or something out of date?
Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.
Thanks — we review requests within 3 business days.
Related guides
About the editors
Researched from the primary sources listed above and checked against our editorial rules before publishing.


