Installing a Plugin

!!! warning The instructions below detail the general process for installing and configuring a NetBox plugin. However, each plugin is different and may require additional tasks or modifications to the steps below. Always consult the documentation for a specific plugin before attempting to install it.

Install the Python Package

Download and install the plugin's Python package per its installation instructions. Plugins published via PyPI are typically installed using the pip command line utility. Be sure to install the plugin within NetBox's virtual environment.

For production installations, the recommended method is to add the package to /opt/netbox/local_requirements.txt and then run NetBox's upgrade script. This installs the plugin as part of the standard NetBox installation and upgrade process and ensures that it will be reinstalled if the virtual environment is rebuilt.

$ sudo sh -c "echo '<package>' >> /opt/netbox/local_requirements.txt"
$ sudo /opt/netbox/upgrade.sh

Installing packages into NetBox's virtual environment requires write permissions to that directory. For installations under /opt/netbox, a regular user typically does not have write permissions. Activating the virtual environment does not change file permissions, so a direct pip install command may result in a Permission denied error.

If you must install a package manually, use one of the following methods. You can switch to a root shell before activating the virtual environment:

$ sudo -i
# source /opt/netbox/venv/bin/activate
(venv) # pip install <package>

Or, run pip by invoking the Python executable within NetBox's virtual environment:

$ sudo /opt/netbox/venv/bin/python3 -m pip install <package>

In the examples above, $ indicates a regular user shell and # indicates a root shell.

Packages that are not published to PyPI may need to be installed from a local source tree. From the package directory, use one of the methods above to run pip install .; for editable development installs, run pip install --editable . instead.

Enable the Plugin

In configuration.py, add the plugin's name to the PLUGINS list:

PLUGINS = [
    # ...
    'plugin_name',
]

Configure the Plugin

If the plugin requires any configuration, define it in configuration.py under the PLUGINS_CONFIG parameter. The available configuration parameters should be detailed in the plugin's README file or other documentation.

PLUGINS_CONFIG = {
    'plugin_name': {
        'foo': 'bar',
        'buzz': 'bazz'
    }
}

!!! note If you ran /opt/netbox/upgrade.sh after enabling and configuring the plugin, the script has already applied database migrations and collected static files. If you ran it only to install the package before enabling the plugin, continue with the migration and static file steps below.

Run Database Migrations

If the plugin introduces new database models, run the provided schema migrations:

(venv) $ cd /opt/netbox/
(venv) $ python3 netbox/manage.py migrate

!!! tip It's okay to run the migrate management command even if the plugin does not include any migration files.

Collect Static Files

Plugins may package static resources like images or scripts to be served directly by the HTTP front end. Ensure that these are copied to the static root directory with the collectstatic management command:

(venv) $ cd /opt/netbox/
(venv) $ python3 netbox/manage.py collectstatic

Restart WSGI Service

Finally, restart the WSGI service and RQ workers to load the new plugin:

$ sudo systemctl restart netbox netbox-rq