Name: ElasticPress

Owner: Rachel Baker

Description: A plugin for integrating WordPress with Elasticsearch

Created: Sep 15, 2015

Updated: Dec 18, 2015

Pushed: Sep 14, 2015


Size: 2656

Language: PHP

GitHub Committers

UserMost Recent Commit# Commits

Other Committers

UserEmailMost Recent Commit# Commits


ElasticPress Build Status Dockunit Status

Integrate Elasticsearch with WordPress.

Please note: the master branch is the stable branch


Let's face it, WordPress search is rudimentary at best. Poor performance, inflexible and rigid matching algorithms (which means no comprehension of 'close' queries), the inability to search metadata and taxonomy information, no way to determine categories of your results and most importantly the overall relevancy of results is poor.

Elasticsearch is a search server based on Lucene. It provides a distributed, multitenant-capable full-text search engine with a RESTful web interface and schema-free JSON documents.

Coupling WordPress with Elasticsearch allows us to do amazing things with search including:


The goal of ElasticPress is to integrate WordPress with Elasticsearch. This plugin integrates with the WP_Query object returning results from Elasticsearch instead of MySQL.

There are other Elasticsearch integration plugins available for WordPress. ElasticPress, unlike others, offers multi-site search. Elasticsearch is a complex topic and integration results in complex problems. Rather than providing a limited, clunky UI, we elected to instead provide full control via WP-CLI.

  1. First, you will need to properly install and configure Elasticsearch.
  2. ElasticPress requires WP-CLI. Install it by following these instructions.
  3. Install the plugin in WordPress. You can download a zip via Github and upload it using the WP plugin uploader.

First, make sure you have Elasticsearch and WP-CLI configured properly.

  1. Define the constant `EP_HOSTin your ``wp-config.php``` file with the connection (and port) of your Elasticsearch application. For example:
ne( 'EP_HOST', '' );

Note: The URL for EP_HOST must begin with a protocol specifier (http or https). URLs without a protocol prefix will not be parsed correctly and will cause ElasticPress to error out.

The proceeding sets depend on whether you are configuring for single site or multi-site with cross-site search capabilities.

Single Site
  1. Activate the plugin.
  2. Using WP-CLI, do an initial sync (with mapping) with your ES server by running the following commands:
lasticpress index --setup
Multisite Cross-site Search
  1. Network activate the plugin
  2. Using WP-CLI, do an initial sync (with mapping) with your ES server by running the following commands:
lasticpress index --setup --network-wide

After your index finishes, `WP_Query` will be integrated with Elasticsearch and support a few special parameters.

Creating Elasticsearch Indices

Creating indices is handled automatically by ElasticPress. Index names are automatically generated based on site URL.


After running an index, ElasticPress integrates with WP_Query if and only if the query is a search or the ep_integrate parameter is passed (see below). The end goal is to support all the parameters available to WP_Query so the transition is completely transparent. Right now, our WP_Query integration supports many of the relevant WP_Query parameters and adds a couple special ones.

Supported WP_Query Parameters

The following are special parameters that are only supported by ElasticPress.

Supported WP-CLI Commands

The following commands are supported by ElasticPress:


Follow the configuration instructions above to setup the plugin.


Within the terminal change directories to the plugin folder. Initialize your testing environment by running the following command:

For VVV users:

 bin/install-wp-tests.sh wordpress_test root root localhost latest

For VIP Quickstart users:

 bin/install-wp-tests.sh wordpress_test root '' localhost latest


Our test suite depends on a running Elasticsearch server. You can supply a host to PHPUnit as an environmental variable like so:

OST="" phpunit

ElasticPress contains a valid Dockunit file for running unit tests across a variety of environments locally (PHP 5.2 and 5.5). It assumes the address of your Elasticsearch server is You can use Dockunit by running:


If you identify any errors or have an idea for improving the plugin, please open an issue. We're excited to see what the community thinks of this project, and we would love your input!


ElasticPress is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This work is supported by the National Institutes of Health's National Center for Advancing Translational Sciences, Grant Number U24TR002306. This work is solely the responsibility of the creators and does not necessarily represent the official views of the National Institutes of Health.