Installing Searx by hand.

06 July 2021

In monitoring the Searx Github repository because I'm a pretty heavy user of this software, I've noticed a common trend. Folks seem to have a hard time getting the automatic installation script to work right. I realize that it would probably make sense to figure out what's going on in there and file a pull request, but given how work's been riding me like a wet pony lately I can't reliably budget time to debug the script under a couple of different distros of Linux and figure out what's wrong. That means that I can't actually help any of the folks who need it, which irritates me. However, with the intent of helping folks get their Searx installs going quickly I have been able to carve out some time to write a manual installation process using my existing notes. So, here goes:

If you're referring to this post I'm going to assume that you already know what Searx is and are having trouble with it. Ubuntu and Debian (and their derivatives) seem to be the new hotness for virtual machines and suchlike, so I'm going to assume them in this text. Substitute equivalent commands as appropriate. Aside from needing Python v3 (which pretty much every distro uses by default these days) you'll need to make sure you have two other packages installed: python3-venv (to set up a virtual environment) and python3-pip (to install Python modules). Of course, you will also need Git. These are present in the basic package repositories of Debian and company.

{15:54:27 @ Fri Jul 02}
[drwho @ windbringer ~] () $ sudo apt-get install -y python3-venv python3-pip git

Now you need to check out the source code for Searx:

{16:02:44 @ Fri Jul 02}
[drwho @ windbringer ~] () $ git clone

Searx has a bunch of dependencies that need to be installed to operate. So, we're going to create a venv, activate it, and install the Python modules Searx needs into it. The cool thing about venvs is that once they're created and activated everything else just goes inside the venv without having to mess around.

{16:03:56 @ Fri Jul 02}
[drwho @ windbringer ~] () $ cd searx/
{16:10:08 @ Fri Jul 02}
[drwho @ windbringer searx] () $ python3 -mvenv env
{16:10:13 @ Fri Jul 02}
[drwho @ windbringer searx] () $ . env/bin/activate
(env) {16:10:40 @ Fri Jul 02}
[drwho @ windbringer searx] () $ pip install -r requirements.txt

You'll see a bunch of output as Python modules are downloaded, their respective dependencies are downloaded, and Pip will probably complain about needing to be updated. You don't have to do this, but if you can if you like:

(env) {16:11:34 @ Fri Jul 02}
[drwho @ windbringer searx] () $ python3 -m pip install --upgrade pip

Now Searx needs to be configured. You do this by editing the searx/settings.yml file with your text editor of choice. I like vim but use whatever you like.

(env) {16:17:14 @ Fri Jul 02}
[drwho @ windbringer searx] () $ vim searx/settings.yml

There are a lot of configuration options you can set - lots of search engines you can turn on or off as you desire, among other things - but there are a couple that you should consider setting, and one that you need to set. The mandatory setting is the secret_key settings in the searx/settings.yml file. As of this writing nothing actually requires it but Searx checks to see if it's been changed and will error out if it's not. So, when you're editing the config file you can set it to whatever junk you want. I use the pwgen command but it doesn't actually matter how you do it.

    port : 8888
    bind_address : "" # address to listen on
    secret_key : "eil5airi0ohjool0eeh0zeit3Osain" # change this!

This is sufficient to have as fully functional Searx instance. I would suggest changing a few other settings to get somewhat better search results:

  • bind_address : - If you plan on running Searx just for yourself - on your laptop or desktop compute, or if you plan on putting it behind a web server, you can leave this as-is. If you want to throw up a Searx instance quickly for the network you're on, change it to something like '' (listen for requests on all network interfaces on this machine).
  • base_url : False - If you're going to proxy Searx through a web server to speed it up (or add HTTPS support), and there's other stuff running on the machine, you can make it look like it's inside a subdirectory of the website. On Leandra I use this setting: base_url : /searx
  • http_protocol_version : "1.0" - There are several different versions of HTTP in use, all of which are slightly different. You can leave this as-is if you want and nothing bad will happen. I set it to "1.1" because it uses additional HTTP requests to pull down assets, which speeds things up a bit.
  • request_timeout : 3.0 - I like to bump this up to something like 60.0 or 120.0 because my home link is kind of slow, and I prefer to wait a bit for results rather than have them time out early and miss some hits.
  • pool_maxsize : 20 - This is the number of persistent connections Searx will keep open. You can increase this if you want. Decreasing it will slow down the process of getting search results. Or you can leave it alone.

Now, start up Searx:

(env) {16:52:01 @ Fri Jul 02}
[drwho @ windbringer searx] () $ python3 searx/ 
 * Serving Flask app "webapp" (lazy loading)
 * Environment: production
   WARNING: This is a development server. Do not use it in a production deployment.
   Use a production WSGI server instead.
 * Debug mode: off
INFO:werkzeug: * Running on (Press CTRL+C to quit)

If you load the URL in your web browser or pull it with a command-line tool you should get the Searx frontpage (or a bunch of HTML if you used the command line) and you'll be good to go.

If you want to automate the process of starting Searx (and you probably do), I recommend putting the commands into a shell script. Here's mine:

#!/usr/bin/env bash


# Change to the Searx installation directory.

# Initialize the Python virtual environment.
. env/bin/activate

# Start up Searx.
python searx/

If you want Searx to start up automatically when the system boots you can call that script from an initscript like /etc/rc.local if you're fortunate enough to have a system that hasn't been infected with systemd. If you're not so fortunate you can use a .service file located in ~/.config/systemd/user/ (if you want Searx to run as you) or /etc/systemd/system if you want it to run at system-level. I just run Searx as myself because I'm the only person who uses it, and I have it call my script. If it doesn't exist already, create a personal systemd directory (mkdir -p ~/.config/systemd/user/) and put the following into a file called searx.service:


# This is the directory you were in when you first cloned Searx.  By default
# this is your personal home directory (%h) but it could theoretically be
# anywhere on the system.

# This is where you call the script.  Again, it defaults to your home
# directory but it can theoretically be anywhere on the system.


Enable and start the service:

{17:09:13 @ Fri Jul 02}
[drwho @ windbringer ~] () $ systemctl --user enable searx.service
{17:09:21 @ Fri Jul 02}
[drwho @ windbringer ~] () $ systemctl --user start searx.service

One last thing: Remember when I mentioned putting Searx behind a webserver earlier? Searx officially supports that for Nginx and Apache. I won't explain how to do that because their documentation does a better job than I can in this regard; follow their directions for your Linux distribution of choice. If you want to do something more elaborate like turn Searx into a UWSGI application I already wrote that up.

Happy hacking.