User Documentation

Upgrade your WordPress site to use Composer

Sign up for Upsun

Get your free trial by clicking the link below.

Get your Upsun free trial

Composer helps you declare, manage, and install all the dependencies needed to run your project. It allows you to make your WordPress site more stable, more secure, and easier to maintain.

With Composer, you don’t need to commit all of WordPress core, its themes and plugins to your project’s Git repository. You also don’t need to manage any of these elements as Git submodules.

Before you begin Anchor to this heading

To update your WordPress site to use Composer, check that:

1. Install WordPress with Composer Anchor to this heading

To install WordPress with Composer, complete the following steps:

  1. Switch to a new Git branch.

    To safely make changes to your repository and environment, run the following command:

    $ git checkout -b composer
  2. Turn your repository into a Composer repository.

    To use Composer, you need:

    • A composer.json file listing all the dependencies needed for your project to run (WordPress itself, its plugins, and its themes).
    • A composer.lock file listing the exact versions of all the dependencies installed on your project. Generated from the composer.json file, it ensures repeatable builds until you update.

    To turn your repository into a Composer repository and generate those files, run the following command:

    $ composer init

    When prompted, set metadata attributes for your project, such as its name and license information. When you get to the part about installing dependencies, type no, as you add them in step 5.

  3. Clean up WordPress core.

    If you’ve been managing WordPress and its dependencies as Git submodules, remove the submodules.

    Otherwise, your existing installation of WordPress core is assumed to be in a subdirectory of your repository (often named wordpress). For Composer to manage WordPress, remove this subdirectory:

    $ rm -rf wordpress

    Then, at the end of your existing .gitignore file, add the content of Platform.shโ€™s template .gitignore file.

    This adds the wordpress subdirectory to the resulting .gitignore file. This way, after Composer reinstalls WordPress, the wordpress subdirectory is ignored in commits.

    Now remove WordPress from the repository:

    $ git rm -rf --cached wordpress && rm -rf wordpress
    $ git add . && git commit -m "Remove WordPress"
  4. Launch the installation of WordPress with Composer.

    Now that you have made your WordPress site into a Composer project, you can download packages via Composer.

    To download WordPress itself, run the following commands:

    $ composer require johnpbloch/wordpress-core-installer
    $ composer require johnpbloch/wordpress-core

    The two dependencies are now listed in your composer.json file:

         "require": {
             "johnpbloch/wordpress-core-installer": "^2.0",
             "johnpbloch/wordpress-core": "^6.0"
  5. Complete the installation:

    $ composer install

    Composer reinstalls WordPress into the wordpress subdirectory.

2. Install WordPress themes and plugins with Composer Anchor to this heading

Just like with WordPress core, you can install themes and plugins with the composer require command. To do so, complete the following steps:

  1. Configure the WPackagist repository.

    By default, when you download dependencies using Composer, you retrieve them through Packagist, which is the primary Composer repository for public PHP packages. Some themes and plugins for WordPress are also on Packagist, but most of them are accessible through a similar service specific to WordPress called WPackagist.

    To allow Composer to download packages from the WPackagist repository, run the following command:

    $ composer config repositories.wppackagist composer

    WPackagist is now listed in your composer.json file:

         "repositories": {
             "wppackagist": {
                 "type": "composer",
                 "url": ""
  2. Optional: Configure theme and plugin destination.

    By default, Composer places installed dependencies in a vendor subdirectory.

    You can configure a different destination for your themes and plugins. For instance, to install them into wp-content, add the following configuration:

     "extra": {
         "installer-paths": {
             "wordpress/wp-content/plugins/{$name}": [
             "wordpress/wp-content/themes/{$name}": [
             "wordpress/wp-content/mu-plugins/{$name}": [

    Make sure you add the new destination subdirectories to your .gitignore file.

    After inspecting package metadata, Composer now installs plugins with a type of wordpress-plugin into wordpress/wp-content/plugins/ instead of vendor. And similarly for themes and must-use plugins.

  3. Launch the installation of plugins and themes with Composer.

    To search for themes and plugins in WPackagist and install them through Composer, run a composer require command:

    # Plugin
    $ composer require wpackagist-plugin/wordpress-seo
    # Theme
    $ composer require wpackagist-theme/hueman

    The two dependencies are now listed in your composer.json file.

  4. Complete the installation:

    $ composer install 

    Each dependency is now installed.

3. Deploy to Anchor to this heading

Switching to a Composer-based installation doesn’t require any modifications to the configuration files created when you deployed your vanilla version. Make sure that your project contains those three files. You can then commit all your changes and deploy your new Composer-based WordPress site to

git add . && git commit -m "Composerify plugins and themes."
git push platform composer

4. Update your Composer-based WordPress site Anchor to this heading

Perform a standard update with Composer Anchor to this heading

Updating WordPress, your themes and plugins becomes a lot simpler with Composer. When a new version becomes available, create a new branch and launch the update:

git checkout -b updates
composer update

Automate your updates with a source operation Anchor to this heading

Tier availability

This feature is available for Elite and Enterprise customers. Compare the tiers on our pricing page, or contact our sales team for more information.

Source operations allow you to automate the maintenance of your Composer-based WordPress site. For instance, you can update all the dependencies in your project with a single command.

Is this page helpful?