ElasticPress moved its built assets to releases, which broke every develop-branch checkout

The 4.0.0 branch split still catches people out

The most operationally important paragraph in the README is a note about version 4.0.0, and it is easy to skim past because it is framed as housekeeping.

As of ElasticPress 4.0.0, `trunk` is the stable branch. Built assets were removed from the `develop` branch. A ZIP containing the plugin and its built assets is published on the GitHub Releases page, and a build script is included so you can build assets from a branch if you want to. The instruction is to update any references you have from `master` to either `trunk` or the GitHub releases, depending on whether you require built assets.

That renames a branch and relocates build output in one release, and the two halves bite differently. Renaming `master` to `trunk` breaks any deployment script that hardcodes the old name, which is a quick failure. Removing built assets from `develop` fails silently: the plugin is present, PHP loads, and the admin interface renders without its styles and scripts. A site running from a develop checkout after 4.0.0 is broken in a way that does not produce an error message.

The default branch for this repository is `develop`, and the badges in the README point at `develop` for the tests status. So the branch a reader lands on is precisely the one without built assets.

The practical rule that follows: if you are installing for production, take the ZIP from the releases page. If you are developing against it, build the assets yourself, which the next section covers.

Building from source means a Node build, not a PHP install

Downloading the repository is explicitly not enough to have the plugin working, because the CSS and JavaScript files are built during the release process.

For a development version you run a Node build, which needs Node.js version 20 and npm version 9:

npm install && npm run build

The build script itself is a call into 10up's shared toolkit, with `10up-toolkit` at `^7.0.0-next.1` in devDependencies, and the scripts separate watching from a one-off build as `build` and `watch`. The packaging step is separate: `build:zip` runs `./bin/build-zip.sh`, which is what produces the artefact on the releases page.

The npm manifest is private, so this is not a package anyone installs from npm. It is a build manifest, and its dependency list is the client side of an admin interface: `@10up/component-tooltip`, `@hello-pangea/dnd` for drag and drop, `@wordpress/icons`, `chart.js` for the analytics views, `focus-trap-react` for accessible modals, `react-router-dom`, `react-slider` and `uuid`. The presence of Chart.js is a hint that the plugin's dashboard draws charts, which is consistent with search analytics being the feature administrators care about.

The PHP side is separate and conventional. `composer.json` and `composer.lock` sit at the root, `phpunit.xml.dist` configures the PHP test suite, `phpcs.xml` the coding standard, and `uninstall.php` handles cleanup on removal, which matters more than usual for a plugin that creates indexes elsewhere. There is also a `tests/e2e` npm workspace and a `single-site.xml.dist`, which is a WordPress multisite configuration file, so multisite is something the project has considered.

Documentation generation is also scripted. `build:docs` removes a `hook_docs` directory and runs jsdoc against `elasticpress.php` and `includes` with `hookdoc-conf.json`, and the `wp-hookdoc` dev dependency is itself a GitHub reference, which is worth noting if you build the docs offline.

What the plugin actually replaces, and the requirements it imposes

The problem statement is about relevance and speed rather than about search being absent. WordPress out of the box struggles to analyse content relevancy and can be very slow, so the plugin replaces the underlying query path rather than the search box.

That means ElasticPress is a client to an external index, and the requirements are the substantive part of adoption. Elasticsearch 5.2 or newer, WordPress 6.2 or newer, and PHP 7.4 or newer. You are adding a running search cluster to a stack that previously had none, and the cluster is now a dependency of your site's core functionality rather than a nice-to-have.

The version floors are worth reading as a compatibility signal rather than a minimum. Requiring Elasticsearch 5.2 puts the floor years below the versions in current use, and CI covers 7.10.1, 8.12.2 and 9.1.5 according to both the `.env.example` comment and the Makefile, with a local default of `ES_VERSION=8.16.1`. Version compatibility across Elasticsearch majors is worth testing in your own environment.

Compatibility is also stated for a specific feature rather than globally: the WooCommerce feature is compatible with the last two major versions of the WooCommerce plugin. That is a narrow promise and it is the kind of detail that matters if you run a store, because WooCommerce content is usually the bulk of what users search for.

For a headless setup there is a separate answer rather than this plugin: ElasticPress React, a separate repository, is pointed at for integrating search into a headless WordPress site.

The 3.5 search algorithm change is the documented break

ElasticPress documents two upgrade notices, and the older one describes a genuine backwards compatibility break rather than a deprecation.

Version 3.5 revamped the search algorithm. The README states plainly that this is a backwards compatibility break, and that the new algorithm offers much more relevant search results and removes fuzziness, which had been producing mostly unwanted results for most people.

The revert is documented as a filter, which means the escape hatch is public API rather than a config option:

add_filter( 'ep_search_algorithm_version', function() { return '3.4'; } );

The warning attached to it is the useful part: if you are hooking in and modifying the search query directly, this change might break your code and you might need to tweak it.

That sentence generalises past 3.5. A search plugin works by intercepting query construction, so any site that filters or overrides WP_Query arguments, or hooks into ElasticPress's own hooks, is coupled to an algorithm whose details are not a stable contract. The repository carries a `hookdoc-conf.json` and a jsdoc pipeline for exactly this hook surface, which suggests the hooks are documented enough to depend on and stable enough to document.

Version 4.0.0 has its own notice, restating the branch rename, the removal of built assets from `develop`, the ZIP on the releases page and the included build script, with the instruction to plan the update of any `master` references.

Two upgrade notices for a plugin at version 5.3.5 is a light list, and the mechanism is consistent: the README tells you how to revert or how to migrate, rather than leaving you to discover breakage in production.

What the test environment reveals about the support matrix

The Makefile is written as a set of named test environments, and it is the clearest statement of what the project actually verifies.

The default goal is `help`, which prints the target list rather than running anything, and the file starts with `-include .env`, so `.env` is optional and a missing file is not fatal. The comment in `.env.example` says `.env` is gitignored and never committed, and that values are read by make so they should avoid `#` and `$`.

The targets fall into groups. `start-e2e` starts wp-env plus Elasticsearch at the configured version, while `start-e2e-epio` starts wp-env alone for use against ElasticPress.io, the hosted service, with the `EPIO_HOST`, `EPIO_CREDENTIALS` and `EPIO_INDEX_PREFIX` variables named after the repository secrets used by the end-to-end workflow. Then `setup-e2e-tests` and `setup-e2e-tests-min` set up the suite against local Elasticsearch, the latter on the minimum supported WordPress and WooCommerce versions, which is how a minimum-support claim gets tested rather than asserted. `setup-e2e-tests-epio` and its minimal variant do the same against the hosted service.

Two details are worth calling out. The `.env.example` sets `ES_VERSION=8.16.1` with a comment that CI covers 7.10.1, 8.12.2 and 9.1.5, and the same three versions appear in a Makefile comment. Testing against three Elasticsearch majors is a real support matrix, and it is the kind of thing that tells you whether a major version bump is likely to break your installation.

The second is the ACF Pro licence. `ACF_PRO_LICENSE_KEY` is optional, and the comment says that without it every target still runs but the tests tagged `@paidPlugins` are skipped. So the suite degrades rather than fails, which is honest, and it also means a contributor without the licence is not running the full end-to-end set.

Unit tests use a MySQL database configured through `WP_TESTS_DB_NAME`, `WP_TESTS_DB_USER`, `WP_TESTS_DB_PASS` and `WP_TESTS_DB_HOST`, with `WP_TESTS_VERSION` defaulting to latest, and the `.env.example` notes that the host value also accepts a socket path. Hooks are managed by husky with a `.lintstagedrc.json`, and a `Makefile` target list plus a `.wordpress-org/` directory indicate this is packaged for the plugin directory as well as GitHub.

Maintenance, licensing and where it loses to alternatives

Support level is stated explicitly rather than implied. The plugin is marked active, and the README says 10up is actively working on it and expects to continue for the foreseeable future, including keeping it tested up to the most recent version of WordPress, with bug reports, feature requests, questions and pull requests welcome.

The repository is not archived, and the last push was on 2026-10-08. Releases are frequent: 5.3.5 on 2026-09-10, 5.3.4 on 2026-08-27 and 5.3.3 on 2026-05-07, so patch releases roughly monthly. The README's licence badge says MIT, while `package.json` declares `GPL-2.0-or-later` and the root file is `LICENSE.md`. Check the file before redistributing.

Where ElasticPress is the wrong choice, the first case is a small site.

The second is a headless setup where you control the front end. There you have options the plugin does not serve, and ElasticPress React is a separate project rather than a feature of this one.

The third is a requirement for exact search semantics you control. ElasticPress translates WP_Query into Elasticsearch queries, which means an Elasticsearch ranking function sits underneath, and its defaults differ from anything a MySQL fulltext index would do. If your results must match a specific expectation rather than be good, test that expectation against real content before you commit.

The fourth is operational appetite. You are taking on an index that must be kept in sync with WordPress content. If nobody on the team owns the Elasticsearch cluster, the search will degrade quietly rather than fail loudly.

Editorial conclusion

ElasticPress fits a WordPress site whose built-in search returns poor or slow results on a large content set, and 10up states an active support level with WordPress kept tested to the current release. Do not adopt it as a drop-in without an Elasticsearch cluster, because the plugin is a front end to an external index rather than a search improvement on its own. Verify first whether your content volume justifies the operational cost, and download from the GitHub releases page rather than a branch if you need built assets, since the develop branch has not shipped them since 4.0.0.

Frequently asked questions

Official sources

1. 10up/ElasticPress on GitHub
2. License: GPL-2.0
3. Project website
4. README
5. Releases