Skip to content



This page provides instructions for setting up the gunicorn WSGI server. If you plan to use uWSGI instead, go here.

NetBox runs as a WSGI application behind an HTTP server. This documentation shows how to install and configure gunicorn (which is automatically installed with NetBox) for this role, however other WSGI servers are available and should work similarly well.


NetBox ships with a default configuration file for gunicorn. To use it, copy /opt/netbox/contrib/ to /opt/netbox/ (We make a copy of this file rather than pointing to it directly to ensure that any local changes to it do not get overwritten during a future NetBox upgrade.)

sudo cp /opt/netbox/contrib/ /opt/netbox/

While the provided configuration should suffice for most initial installations, you may wish to edit this file to change the bound IP address and/or port number, or to make performance-related adjustments. See the Gunicorn documentation for the available configuration parameters.

systemd Setup

We'll use systemd to control both gunicorn and NetBox's background worker process. First, copy contrib/netbox.service and contrib/netbox-rq.service to the /etc/systemd/system/ directory and reload the systemd daemon.

Check user & group assignment

The stock service configuration files packaged with NetBox assume that the service will run with the netbox user and group names. If these differ on your installation, be sure to update the service files accordingly.

sudo cp -v /opt/netbox/contrib/*.service /etc/systemd/system/
sudo systemctl daemon-reload

Then, start the netbox and netbox-rq services and enable them to initiate at boot time:

sudo systemctl enable --now netbox netbox-rq

You can use the command systemctl status netbox to verify that the WSGI service is running:

systemctl status netbox.service

You should see output similar to the following:

● netbox.service - NetBox WSGI Service
     Loaded: loaded (/etc/systemd/system/netbox.service; enabled; vendor preset: enabled)
     Active: active (running) since Mon 2021-08-30 04:02:36 UTC; 14h ago
   Main PID: 1140492 (gunicorn)
      Tasks: 19 (limit: 4683)
     Memory: 666.2M
     CGroup: /system.slice/netbox.service
             ├─1140492 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /va>
             ├─1140513 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /va>
             ├─1140514 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /va>


If the NetBox service fails to start, issue the command journalctl -eu netbox to check for log messages that may indicate the problem.

Once you've verified that the WSGI workers are up and running, move on to HTTP server setup.


There is a bug in the current stable release of gunicorn (v21.2.0) where automatic restarts of the worker processes can result in 502 errors under heavy load. (See gunicorn bug #3038 for more detail.) Users who encounter this issue may opt to downgrade to an earlier, unaffected release of gunicorn (pip install gunicorn==20.1.0). Note, however, that this earlier release does not officially support Python 3.11.