Installing NetBox Plugins in Docker: A Complete Guide (2025)

Allgemein

Introduction

If you’re running NetBox in Docker and trying to install plugins, you’ve probably encountered the frustration of build failures, missing pip commands, and cryptic error messages. After hours of trial and error, I’ve finally cracked the code, and I’m sharing the complete solution here.

This guide covers:

  • Setting up NetBox with Docker on Synology NAS (but works on any Docker host)
  • Installing plugins (netbox-topology-views and netbox-secrets)
  • Troubleshooting common issues
  • A working Dockerfile and deployment strategy

What is NetBox?

NetBox is an open-source network source of truth (NSoT) and IPAM (IP Address Management) tool. Originally built by the team at DigitalOcean, it’s now maintained by the NetBox community. It’s perfect for:

  • Managing network infrastructure
  • Tracking devices, cables, and connections
  • IP address management
  • Documenting data center resources
  • Creating network topology visualizations

For home lab enthusiasts and small businesses, NetBox provides enterprise-grade network documentation without the enterprise price tag.

The Challenge: Installing Plugins in Docker

While NetBox itself is straightforward to deploy using the official netboxcommunity/netbox Docker image, adding plugins is where things get complicated. The official documentation exists, but scattered across wikis and GitHub issues, it’s easy to miss critical details.

Common Problems You’ll Encounter

Problem 1: Wrong pip command

RUN pip install -r /tmp/plugin_requirements.txt
# Error: pip: command not found

Problem 2: Wrong pip path

RUN /opt/netbox/venv/bin/pip install -r /tmp/plugin_requirements.txt
# Error: /opt/netbox/venv/bin/pip: not found

Problem 3: SECRET_KEY too short

RUN SECRET_KEY="dummy-key" python manage.py collectstatic --no-input
# Error: SECRET_KEY must be at least 50 characters in length

Problem 4: Portainer can’t find the image

Error: repository does not exist or may require 'docker login': denied

Sound familiar? Let’s fix all of these.

The Solution: Step-by-Step

Prerequisites

  • Docker host (Synology NAS, Ubuntu server, etc.)
  • Portainer (optional, but recommended)
  • SSH access to your Docker host
  • Basic understanding of Docker and Docker Compose

Step 1: Create Plugin Requirements File

Create plugin_requirements.txt with the plugins you want:

netbox-topology-views==4.4.0
netbox-secrets==2.4.1
pycryptodome

Important: Check plugin compatibility with your NetBox version! Visit the plugin’s GitHub repository to find the correct version.

Step 2: Create the Dockerfile

Here’s the correct Dockerfile that actually works:

FROM netboxcommunity/netbox:latest

# Switch to root to install packages and create directories
USER root

# Copy plugin requirements
COPY ./plugin_requirements.txt /opt/netbox/

# Install plugins using uv (the official way in netbox-docker)
# THIS IS THE KEY - use /usr/local/bin/uv pip install, not plain pip!
RUN /usr/local/bin/uv pip install -r /opt/netbox/plugin_requirements.txt

# Create required directory for Topology Views images
RUN mkdir -p /opt/netbox/netbox/static/netbox_topology_views/img && 
    chown -R unit:root /opt/netbox/netbox/static/netbox_topology_views

# Collect static files
# SECRET_KEY must be 50+ characters!
RUN SECRET_KEY="dummyKeyWithMinimumLength-------------------------" 
    /opt/netbox/venv/bin/python /opt/netbox/netbox/manage.py collectstatic --no-input

# Switch back to unit user
USER unit

WORKDIR /opt/netbox/netbox

Key Insights:

  • Use /usr/local/bin/uv pip install instead of plain pip or /opt/netbox/venv/bin/pip
  • The SECRET_KEY for collectstatic must be exactly 50+ characters
  • Switch back to the unit user for security

Step 3: Configure the Plugins

Create plugins.py with your plugin configuration:

# NetBox Plugins Configuration

PLUGINS = [
    'netbox_topology_views',
    'netbox_secrets'
]

PLUGINS_CONFIG = {
    'netbox_topology_views': {
        'static_image_directory': 'netbox_topology_views/img',
        'allow_coordinates_saving': True,
        'always_save_coordinates': True
    },
    'netbox_secrets': {
        'top_level_menu': True,
        'public_key_size': 2048
    }
}

Step 4: Build the Custom Image

Important: Build the image on the same machine where Docker will run it!

If using Synology NAS with SSH:

ssh -p 9022 your-user@your-nas-ip "cd /volume1/docker/NetBox && 
  echo 'your-password' | sudo -S docker build 
  -f Dockerfile-Plugins -t netbox:custom-plugins ."

For standard Linux Docker host:

cd /path/to/netbox
docker build -f Dockerfile-Plugins -t netbox:custom-plugins .

You should see output like:

Step 4/8 : RUN /usr/local/bin/uv pip install -r /opt/netbox/plugin_requirements.txt
 ---> Running in 75e736dc4f94
Resolved 3 packages in 173ms
Installed 3 packages in 26ms
 + netbox-secrets==2.4.1
 + netbox-topology-views==4.4.0
 + pycryptodome==3.23.0
Successfully tagged netbox:custom-plugins

Step 5: Create Docker Compose File

Create docker-compose-with-plugins.yml:

version: '3.8'

services:
  netbox:
    image: netbox:custom-plugins
    pull_policy: never  # Critical: prevents Docker from trying to pull from registry
    container_name: netbox
    depends_on:
      - redis
      - redis-cache
    environment:
      - CORS_ORIGIN_ALLOW_ALL=true
      - DB_HOST=your-db-host
      - DB_PORT=5432
      - DB_NAME=netbox
      - DB_USER=netbox
      - DB_PASSWORD=your-db-password
      - REDIS_HOST=redis
      - REDIS_CACHE_HOST=redis-cache
      - REDIS_PASSWORD=your-redis-password
      - SECRET_KEY=your-50-character-secret-key-here-make-it-long
      - SUPERUSER_NAME=admin
      - SUPERUSER_EMAIL=admin@example.com
      - SUPERUSER_PASSWORD=admin
      - SUPERUSER_API_TOKEN=0123456789abcdef0123456789abcdef01234567
    volumes:
      - ./media:/opt/netbox/netbox/media
      - ./reports:/opt/netbox/netbox/reports
      - ./scripts:/opt/netbox/netbox/scripts
      - ./configuration.py:/etc/netbox/config/configuration.py:ro
      - ./plugins.py:/etc/netbox/config/plugins.py:ro
      - ./plugin_images:/opt/netbox/netbox/static/netbox_topology_views/img:rw
    ports:
      - 8080:8080
    restart: unless-stopped

  netbox-worker:
    image: netbox:custom-plugins
    pull_policy: never
    container_name: netbox-worker
    depends_on:
      - netbox
      - redis
    environment:
      # Same environment variables as netbox service
    command: /opt/netbox/venv/bin/python /opt/netbox/netbox/manage.py rqworker
    volumes:
      # Same volumes as netbox service (except port mapping)
    restart: unless-stopped

  netbox-housekeeping:
    image: netbox:custom-plugins
    pull_policy: never
    container_name: netbox-housekeeping
    depends_on:
      - netbox
      - redis
    environment:
      # Same environment variables as netbox service
    command: /opt/netbox/housekeeping.sh
    volumes:
      # Same volumes as netbox service (except port mapping)
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    container_name: netbox-redis
    command: redis-server --appendonly yes --requirepass your-redis-password
    volumes:
      - ./redis-data:/data
    restart: unless-stopped

  redis-cache:
    image: redis:7-alpine
    container_name: netbox-redis-cache
    command: redis-server --requirepass your-redis-password
    restart: unless-stopped

Critical setting: pull_policy: never tells Docker to use the local image instead of trying to pull from Docker Hub.

Step 6: Deploy

Using Portainer:

  1. Navigate to Stacks → Add stack
  2. Upload your docker-compose-with-plugins.yml
  3. Click „Deploy the stack“

Using command line:

docker compose -f docker-compose-with-plugins.yml up -d

Step 7: Verify Installation

Check if plugins are installed:

docker exec netbox /opt/netbox/venv/bin/pip list | grep netbox

You should see:

netbox-secrets          2.4.1
netbox-topology-views   4.4.0

Access NetBox at http://your-server-ip:8080 and look for:

  • „Plugins“ menu in the navigation
  • „Topology Views“ under Plugins
  • „Secrets“ under Plugins

Troubleshooting

Build fails with „pip: command not found“

Solution: Use /usr/local/bin/uv pip install instead of plain pip. The NetBox Docker image uses UV (ultra-fast Python package installer) which is located at /usr/local/bin/uv.

Build fails with „SECRET_KEY must be at least 50 characters“

Solution: Ensure your SECRET_KEY in the Dockerfile’s collectstatic step is at least 50 characters:

RUN SECRET_KEY="dummyKeyWithMinimumLength-------------------------" 
    /opt/netbox/venv/bin/python /opt/netbox/netbox/manage.py collectstatic --no-input

Portainer shows „repository does not exist“ error

Solution: Add pull_policy: never to each service in your docker-compose file. This tells Docker to use the locally built image instead of trying to pull it from a registry.

Plugins don’t show up in NetBox

Solutions:

  1. Verify plugins.py is mounted correctly: – ./plugins.py:/etc/netbox/config/plugins.py:ro
  2. Check plugin names match exactly (underscores vs hyphens)
  3. Run migrations: docker exec netbox python /opt/netbox/netbox/manage.py migrate
  4. Check container logs: docker logs netbox

Need to rebuild after changing plugins

# On your Docker host
docker build --no-cache -f Dockerfile-Plugins -t netbox:custom-plugins .

# Then restart containers
docker compose restart netbox netbox-worker netbox-housekeeping

Why This Approach Works

  1. UV Package Manager: NetBox Docker images use UV, a modern Python package installer that’s faster than pip. Using /usr/local/bin/uv pip install is the officially supported method.
  2. Local Image Build: Building the image on the same machine where it runs avoids registry push/pull complications.
  3. Static File Collection: Running collectstatic during the build ensures plugin static files (CSS, JS, images) are available.
  4. Proper Permissions: Switching to unit user after installation maintains security.

Alternative: Using docker-compose.override.yml

The official NetBox Docker documentation suggests using docker-compose.override.yml with a build context. This works if:

  • You’re running Docker locally (not through Portainer)
  • You want automatic rebuilds
  • You have the NetBox repository cloned

Example:

services:
  netbox:
    image: netbox:latest-plugins
    pull_policy: never
    build:
      context: .
      dockerfile: Dockerfile-Plugins

However, this doesn’t work well with Portainer’s build context limitations, which is why the pre-built image approach is more reliable.

Updating NetBox or Plugins

To update NetBox base version:

docker pull netboxcommunity/netbox:latest
docker build --no-cache -f Dockerfile-Plugins -t netbox:custom-plugins .
docker compose restart

To add/update plugins:

  1. Edit plugin_requirements.txt
  2. Edit plugins.py if needed
  3. Rebuild the image
  4. Run migrations

Conclusion

Installing NetBox plugins in Docker doesn’t have to be painful. The key insights are:

  1. Use /usr/local/bin/uv pip install (not plain pip)
  2. Ensure SECRET_KEY is 50+ characters in the Dockerfile
  3. Set pull_policy: never in docker-compose
  4. Build the image on the same machine where it will run
  5. Mount plugins.py to /etc/netbox/config/plugins.py

I spent 6+ hours figuring this out, going through dozens of GitHub issues, wiki pages, and failed builds. Hopefully, this guide saves you that time!

Resources

Questions or Issues?

Drop a comment below! I’ll do my best to help troubleshoot any issues you encounter.

Last updated: December 2025 | NetBox v4.2+ | Docker 20.10+