Documentation

Add the WP Packages repository to your project:

Every active plugin and theme from the WordPress.org directory is available as a Composer package. Search all packages →

Package naming

Example composer.json

{
  "repositories": [
    {
      "name": "wp-packages",
      "type": "composer",
      "url": "https://repo.wp-packages.org"
    }
  ],
  "require": {
    "composer/installers": "^2.2",
    "wp-plugin/woocommerce": "^10.0",
    "wp-theme/twentytwentyfive": "^1.0"
  },
  "extra": {
    "installer-paths": {
      "wp-content/plugins/{$name}/": ["type:wordpress-plugin"],
      "wp-content/mu-plugins/{$name}/": ["type:wordpress-muplugin"],
      "wp-content/themes/{$name}/": ["type:wordpress-theme"]
    }
  }
}

WordPress core Composer packages

Roots also provides WordPress core as Composer packages:

Learn more about the WordPress core Composer packages →

Migrating from WPackagist

See how WP Packages compares to WPackagist →

Switching from WPackagist takes one command. Use the migration script to automatically update your composer.json:

Manually migrate

Changelog action

roots/wp-packages-changelog-action is a GitHub Action that automatically comments on pull requests with a changelog summary for any WP Packages dependencies that changed.

When a PR updates your composer.lock, the action compares the before and after versions and posts a comment with the relevant changelog entries from WordPress.org. It also warns when an installed version doesn’t match the current WordPress.org stable tag, helping you catch outdated or mismatched dependencies before merging.

Usage

name: Changelog
on:
  pull_request:
    paths:
      - composer.lock

jobs:
  changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: roots/wp-packages-changelog-action@v3
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

API

WP Packages provides a public JSON API for install statistics.

GET /api/stats

Returns overall install statistics.

{
  "total_installs": 123456,
  "total_installs_formatted": "123k",
  "installs_30d": 7890,
  "installs_30d_formatted": "8k",
  "active_plugins": 500,
  "active_themes": 200,
  "total_packages": 700
}

GET /api/stats/packages/{type}/{name}

Returns monthly install history for a specific package (up to 36 months). The type can be wp-plugin or wp-theme.

[
  { "month": "2026-01", "installs": 142 },
  { "month": "2026-02", "installs": 88 }
]

GET /api/stats/packages/{type}/{name}/total

Returns the total Composer install count and the last 30 days of installs for a single package. Designed for use in shields.io badges.

{
  "total_installs": 1234567,
  "total_installs_formatted": "1.2M",
  "installs_30d": 45678,
  "installs_30d_formatted": "46k"
}

GET /api/packages/{type}/closed

Returns a sorted list of slugs for plugins or themes that are currently closed on wp.org — including both temporary and permanent closures. The type can be wp-plugin or wp-theme.

[
  "closed-plugin-slug-a",
  "closed-plugin-slug-b"
]

GET /api/packages/{type}/closed/permanent

Returns the subset of closed packages that have been flagged as permanently closed on wp.org. Use this endpoint when you only want to surface closures unlikely to ever reopen.

[
  "closed-plugin-slug-a",
  "closed-plugin-slug-b"
]

GET /api/closures

Returns a paginated list of mass-closure events detected in rolling 24-hour windows.

{
  "events": [
    {
      "id": 42,
      "vendor_name": "WPFactory",
      "vendor_slug": "wpfactory",
      "detected_at": "2026-04-27T13:03:45Z",
      "detected_at_formatted": "April 27, 2026",
      "plugin_slugs": ["plugin-a", "plugin-b"],
      "plugin_count": 2
    }
  ],
  "page": 1,
  "per_page": 50,
  "total": 6,
  "total_pages": 1,
  "documentation_url": "https://wp-packages.org/docs#api-closures"
}

GET /api/closures/{vendor_slug}

Returns all historical mass-closure events for a specific vendor.

{
  "events": [
    {
      "id": 42,
      "vendor_name": "WPFactory",
      "vendor_slug": "wpfactory",
      "detected_at": "2026-04-27T13:03:45Z",
      "detected_at_formatted": "April 27, 2026",
      "plugin_slugs": ["plugin-a", "plugin-b"],
      "plugin_count": 2
    }
  ],
  "documentation_url": "https://wp-packages.org/docs#api-vendor-closures"
}

Stats responses are cached for 5 minutes; the closed-packages and closures endpoints are cached for 1 hour. Returns 404 for inactive or unknown packages, and 429 when rate limited.

Badges for plugin authors

If you maintain a plugin or theme on WordPress.org, show your Composer install count in your README using shields.io. The badge updates automatically as installs grow.

Live badge for wp-plugin/woocommerce

Add this to your README, replacing your-plugin with your plugin slug:

For themes, change wp-plugin to wp-theme in the URL. You can customize the label, color, and style with shields.io's URL parameters — see the shields.io docs.