Skip to content
Back to top
View this page
Edit this page

# Development Quickstart

SearXNG loves developers; Developers do not need to worry about tool chains, the usual developer tasks can be comfortably executed via make.

Don’t hesitate, just clone SearXNG’s sources and start hacking right now ..

    git clone https://github.com/searxng/searxng.git searxng

For the developer environment, mise en place is recommended:

    $ curl https://mise.run | sh

The tools required for a developer environment are provided via mise.toml, trust the project:

    $ mise trust

Here is how a minimal workflow looks like:

1. start hacking

2. run your code: make run

3. format & test your code: make format and make test

If you think at some point something fails, go back to start. Otherwise, choose a meaningful commit message and we are happy to receive your pull request. To not end in wild west we have some directives, please pay attention to our “How to contribute” guideline.

If you want to debug with the good old Python Debugger pdb: Alternatively to `make run` (2.) which starts a Granian server you can jump into the developer environment and start a python based HTTP server by:

    $ ./manage dev.env
    ...
    (dev.env)$ SEARXNG_DEBUG=1 searxng-run

Since this is a pure Python solution, you can set breakpoints in your code with `pdb.set_trace()` and the debugger will wait for you in the terminal prompt.

Any other script or command line provided by SearXNG can also be used in the same environment, here are a few examples:

    # tools related to favicons
    (dev.env)$ python -m searx.favicons

    # tools related to DATA stored in searx/data
    (dev.env)$ python -m searx.data --help

    # tools related to engines
    (dev.env)$ python -m searx.enginelib --help

    # to test one of the update scripts
    (dev.env)$ searxng_extra/update/update_engine_traits.py --help

    # to test the update of the wikidata units
    (dev.env)$ searxng_extra/update/update_wikidata_units.py

If you implement themes, you will need to setup a Node.js environment. Before you call make run (2.), you need to compile the modified styles and JavaScript: `make node.clean themes.all`. If Biome or Stylelint reports issues, try `make themes.fix`.

Alternatively you can also compile selective the theme you have modified, e.g. the simple theme.

    make themes.simple

Tip

To get live builds while modifying CSS & JS use: `LIVE_THEME=simple make run`

If you finished your tests you can start to commit your changes. To separate the modified source code from the build products first run:

    make static.build.restore

This will restore the old build products and only your changes of the code remain in the working tree which can now be added & committed. When all sources are committed, you can commit the build products simply by:

    make static.build.commit

Committing the build products should be the last step, just before you send us your PR. There is also a make target to rewind this last build commit:

    make static.build.drop