# Plugins

Plugins can extend or replace functionality of various components of searx.

## Example plugin

    name = 'Example plugin'
    description = 'This plugin extends the suggestions with the word "example"'
    default_on = False  # disabled by default

    # attach callback to the post search hook
    #  request: flask request object
    #  ctx: the whole local context of the post search hook
    def post_search(request, search):
        search.result_container.suggestions.add('example')
        return True

## External plugins

SearXNG supports external plugins / there is no need to install one, SearXNG runs out of the box. But to demonstrate; in the example below we install the SearXNG plugins from The Green Web Foundation [ref]:

    $ sudo utils/searxng.sh instance cmd bash -c
    (searxng-pyenv)$ pip install git+https://github.com/return42/tgwf-searx-plugins

In the settings.yml activate the `plugins:` section and add module `only_show_green_results` from `tgwf-searx-plugins`.

    plugins:
      ...
      - only_show_green_results
      ...

## Plugin entry points

Entry points (hooks) define when a plugin runs. Right now only three hooks are implemented. So feel free to implement a hook if it fits the behaviour of your plugin. A plugin doesn’t need to implement all the hooks.

pre_search(request, search) → bool

  Runs BEFORE the search request.

  search.result_container can be changed.

  Return a boolean:

  - True to continue the search

  - False to stop the search

  Parameters:

    - request (flask.request)

    - search (searx.search.SearchWithPlugins)

  Returns:

    False to stop the search

  Return type:

    bool

post_search(request, search) → None

  Runs AFTER the search request.

  Parameters:

    - request (flask.request) – Flask request.

    - search (searx.search.SearchWithPlugins) – Context.

on_result(request, search, result) → bool

  Runs for each result of each engine.

  result can be changed.

  If result[“url”] is defined, then result[“parsed_url”] = urlparse(result[‘url’])

  Warning

  result[“url”] can be changed, but result[“parsed_url”] must be updated too.

  Return a boolean:

  - True to keep the result

  - False to remove the result

  Parameters:

    - request (flask.request)

    - search (searx.search.SearchWithPlugins)

    - result (Dict) – Result, see - Result Types (template)

  Returns:

    True to keep the result

  Return type:

    bool