WordPress Sphinx Search Tutorial

Download the latest version from wordpress.org

Home page | Description | Installation | FAQ | Screenshots| Support


WordPress Sphinx Search Plugin allows to use Sphinx Search Server power to enable ultra-fast and feature-rich search on WordPress-based websites. It is especially useful if your WordPress site becomes very large.

Search results are more relevant and you can search in posts, pages and comments using flexible search syntax, quickly sort the results by freshness or relevance. This plugin comes with sidebar widgets to display the most recent searches and top and related search terms.

This plugin replaces WordPress’s built-in search functionality.


  • Use flexible search syntax
  • Sort search results by Relevance or Freshness
  • Search in posts, pages and comments
  • Friendly URLs support New!
  • Use extended search form to fine tune the results
  • Use sidebar widget for displaying Related/Top search terms
  • Use sidebar widget for displaying Latest search terms
  • Use Settings to style the keyword highlighting and search results
  • Sphinx configuration Wizard (via Settings)

Flexible search syntax

Sphinx allows you to use the following special operators in searchbox:

    1. Operator OR: hello | world
    2. Operator NOT: hello -world, hello !world
    3. Field search operator: @title hello @body world

The following field operators are available:
@title – search in title of post or page
@body – search in body of post, page or comment
@category – search in blog categories

  1. Phrase search operator: “hello world”
  2. Proximity search operator: “hello world”~10

Here’s an example query which uses all these operators:

"hello world" @title "example program"~5 @body python -(php|perl)

Read more on extended search syntax on Sphinx website: //sphinxsearch.com/doc.html#extended-syntax



  • WordPress 2.0.2 or higher
  • Ability to install Sphinx if not installed
  • Writable WordPress upload directory for Sphinx configuration files, logs and indexes

Step-by-step installation guide

Install the plugin:

  1. Unpack the plugin archive to wp-content/plugins folder of your WordPress installation
  2. Activate Sphinx Search plugin via WordPress Settings
  3. Make sure WordPress upload directory is writable by web server (by default WordPress is configured to use wp-content/uploads)
  4. Open Sphinx Search settings page and follow by Wizard steps to setup Sphinx Search Server and plugin configuration

Sphinx Configuration Wizard
Configuration Wizard

Most important steps:

  • In the 2nd wizard step you define Sphinx connection parameters which are used later by Sphinx Server.
  • In the 3rd step you may choose to use already installed Sphinx on your system (if exists) or install it from the latest installation archive that comes with plugin. If you choose to install Sphinx Server via wizard, be patient to wait several minutes while it finishes.
  • Then you need to specify paths to the Sphinx files like: indexes, config file and logs. (By default in our plugin these paths are set in the WordPress upload directory).
  • The following step will ask to run the indexer to build the search index. You may skip this step and index your data later on the plugin Settings page.
  • In “Configuration file” step you are informed about where the sphinx.conf is stored, also in this step you may open sphinx.conf configuration file generated by wizard.

Setup scheduled jobs to re-index your website data periodically

To setup periodical re-indexing, you should run Wizard to create special schedule files.

The default location of these files is: /path/to/wp-content/uploads/sphinx/cron/. When wizard finishes, edit your Crontab file.
Use “crontab -e” command in the Linux terminal and add the following lines to your crontab:

#Wordpress Delta index update
#Following cron job update delta index every 5 minutes:
*/5 * * * * /usr/bin/php /path/to/wp-content/uploads/sphinx/cron/cron_reindex_delta.php
#Wordpress Main index update
#Following cron job update main index daily (at 0 hours and 5 minutes):
5 0 * * * /usr/bin/php /path/to/wp-content/uploads/sphinx/cron/cron_reindex_main.php

Extended search form on search results page

<?php if (function_exists('ss_search_bar'))
    echo ss_search_bar();/*put it in search page*/?>

To find out if the current post is comment

<?php if (function_exists('ss_isComment') )
    if (ss_isComment()) echo 'It is comment'; else echo '';?>

Highlight search term in post title
Use the following function instead of the_title()

<?php sphinx_the_title(); ?>

Extended search form at the sidebar
Use “Sphinx Search sidebar” widget or add it as template tag:

<?php if (function_exists('ss_search_bar'))
    echo ss_search_bar(true); /*put it in sidebar*/?>

Related/Top searches at the sidebar
Use “Sphinx Related/Top Searches” widget or add it as template tag:

<?php if (function_exists('ss_top_searches')) ss_top_searches(); ?>

Top searches with pagination
Use “ss_top_searches_pager($max_per_page=10, $show_all=false)” template tag to enable pagination for top search terms:

<?php if (function_exists('ss_top_searches_pager')) ss_top_searches_pager(); ?>

* $max_per_page – limit how many search terms to display per page, by default 10
* $show_all – If set to True, then it will show all of the pages instead of a short list of the pages near the current page. By default, the ‘show_all’ is set to false

Latest searches at the sidebar
Use “Sphinx Latest Searches” widget or add it as template tag:

<?php if (function_exists('ss_latest_searches')) ss_latest_searches(); ?>


Q: What is Sphinx Search Server?
A: Sphinx is a full-text search engine which provides fast and relevant full-text search functionality. Read more on Sphinx website //sphinxsearch.com

Q: How to install Sphinx Search manually?
A: To manually install Sphinx use the official Sphinx Search documentation.

Q: How to update the search index?
A: The best option to update search index is to setup cron job task for it. Also you may manually update search indexes through WordPress Sphinx Search administrative interface.

Q: How to run indexer manually
A: Open terminal and run following command:
/path/to/indexer -c /path/to/sphinx.conf --rotate --all

Q: I have just installed and run the wizard, however I have the following error message. What to do?
Can not start searchd, try to start it manually.

A: If you use version 2.1 or higher you can see the exact command below message “Can not start searchd, try to start it manually.” which you need to run manually through terminal on your server.
If you have ‘Permissions problem’ try to run the command as super user.

Q: When I run searchd or indexer I got ERROR: invalid section type ‘X-Powered-By’ in ../sphinx.conf line 1 col 1.
A: You are using CGI version of php, by default it shows a http header like “X-Powered-By: PHP/4.3.6”
To prevent this, PHP needs to be invoked with the ‘-q’ option for ‘quiet’. Open sphinx.conf in editor and change first line to:
#!/usr/bin/php -q

Q: I got WARNING: index ‘wp_main’: preload: failed to open /path/to/indexes/wp_main.sph No such file or directory; NOT SERVING
A: That means you have no indexes to serve. You need to build them. You may do it via wp-admin or manually:
On wp-admin>Settings>Sphinx Search page click “Re-index WordPress index”
Or use run this command manually in terminal:
/path/to/indexer -c /path/to/etc/sphinx.conf --all --rotate

Q: Sphinx installs fine, but when I go to search for something on the blog I get no results.
A: Check Sphinx version, Sphinx version should be 0.9.9 or higher.

Q: How do I modify the plugin php script to specify the path where I have Sphinx installed?
A: Run Sphinx Configuration wizard from WP Admin panel.
There are two important steps:
1. Install or use existing Sphinx binaries
There you can specify the path to your own indexer and searchd
2. Setup path to Sphinx indexes
There you can specify where to store index files and sphinx.conf file. This path should be writeable by web server.

Q: Cannot activate plugin. If I try to activate the plugin I get the following PHP error:
Fatal error: Cannot redeclare class SphinxClient in /home/wordpress/wp-content/plugins/wordpress-sphinx-plugin/php/sphinxapi.php

A: Check that you haven’t:
1. any other plugins which loaded Sphinx Search API library
2. Sphinx Search PECL extension installed

Q: I’ve got an error “Indexer: configuration files not found.” on clicking “Run Indexing & Contunue” (“Sphinx data indexing” step of Wizard).
A: Check that the user which is running your web server (it’s usually apache, www-data or smth like this)
can run indexer/searchd and can read/write into sphinx.conf. Then run Sphinx Configuration wizard from WP Admin panel again.

Q: How to set the maximum number of search results above 100.000?

1) Go to Sphinx Search plugin directory and open rep/sphinx.conf in text editor.
2) Find max_matches parameter in searchd section at the bottom of the file
3) Set new value i.e. max_matches = 1000000
4) Open Sphinx Search control panel in WP Admin
5) Click on “Run Sphinx configuration Wizard” and skip all steps in the Wizard, it will rebuilds sphinx.conf file at the last step, click Finish.
6) Restart Sphinx Search (click on “Stop Sphinx daemon” and then “Start Sphinx daemon”)
7) Open tab “Search settings” and set the same max_matches value in the field “Maximum number of search results”.

Q: My site is hosted on a shared server. Will WP Sphinx plugin run in my environment?
A: You need to make sure that you or your hosting administrator can install Sphinx on the server and that you have permissions to access it. You must have full control your WP installation, i.e. permissions to do whatever you want inside the WP directory;  and 2) run binaries (you will need to start the Sphinx searchd daemon).


Search in action:
Search results
Sidebar widgets

Top search terms widget:
Top search terms widget

Related search terms widget:
Related search terms

Latest search terms widget:
Latest search terms

Extended search form:
Extended Sphinx Search form

This search form is build as replacement for standard search form and it has following features:

  • Sort search results by Relevance or Freshness
  • Toggle search in posts, in pages and in comments
  • Exclude posts, comments or pages from search results


This plugin is developed by Ivinco. If you need commercial support, or if you’d like WordPress Sphinx Search Plugin customized for your needs, we can help. Visit plugin website for the latest news.
See release notes, report bugs and feature wishes on WordPress: //wordpress.org/extend/plugins/wordpress-sphinx-plugin/