How To Update NetBox Docker

First of all, before you update, always read the release notes of the NetBox Docker project. If a new version of NetBox is rolled out, be sure to also check the release notes of NetBox itself.

When you followed our Getting Started instructions instruction to get NetBox Docker running, then you should be able to follow this guide just fine. Otherwise you will have to figure out the analogous steps yourself.

Update steps

IMPORTANT: Please make a backup of your data before updating! Our Troubleshooting page has some information regarding this.

First, open a terminal and cd to your project folder. This is the folder where the docker-compose.yml file is.

Now, stop all the containers that are running:

docker compose down

Then, to update to the latest release, fetch all updates to the project files from the release channel:

git checkout release &&
git pull -p origin release

NOTE: If you instead want to update to a specific version, see the respective guide.

Now you need to tell Docker to fetch the latest NetBox Docker Container and also to fetch new version of the dependencies, such as a new Redis or PostgreSQL:

docker compose pull

Now it's time to start all the containers again. This will also migrate the NetBox database schema automatically.

docker compose up -d

Once NetBox has started, you should be ready to go.

Common Issues

Updating from below 1.x.x to 1.x.x

Don't forget to update the docker-compose.override.yml file, as described in the release notes.

PostgreSQL Update

Updates between major versions of PostgreSQL (e.g. version 11 to 12) require special attention. The easiest way to perform such an update is to backup the database on the old version and restore the data on the new version:

⚠️ IMPORTANT: Make sure to test this procedure first before applying it to valuable data ⚠️

cd <path_to>/netbox-docker

# Stop all containers
docker compose down

# Only start the DB
docker compose up -d postgres

# Take a DB backup
docker compose exec -T postgres sh -c 'pg_dump -cU $POSTGRES_USER $POSTGRES_DB' | gzip > db_dump.sql.gz

# Stop the database
docker compose down

# Remove the database volume
# 
# !!!
# THIS STEP WILL REMOVE ALL DATA IN YOUR DATABASE
# !!!
docker volume rm netbox-netbox-postgres-data

# Update NetBox Docker files and containers
git checkout release && git pull -p origin release
docker compose pull

# Restore the database
docker compose up -d postgres
gunzip -c db_dump.sql.gz | docker compose exec -T postgres sh -c 'psql -U $POSTGRES_USER $POSTGRES_DB'

# Start all other containers
docker compose up -d