Version

Using a Specific Version of NetBox

In order to use a specific version of NetBox, you need to check out the respective version of NetBox Docker. Carefully check the release notes to learn which version of NetBox Docker works with which version of NetBox.

Your most important resource when selecting a valid image is the list of tags on the docker up: https://hub.docker.com/r/netboxcommunity/netbox/tags Identify here the target netbox version you'd like, then find the netbox-docker version on the release page that suppports it. Do the same thing for your currently running versions.

If you are coming from old versions, also check the requirements for netbox itself (i.e. the PostgreSQL version) https://netboxlabs.com/docs/netbox/installation/upgrading/

Then proceed to checkout the respective NetBox Docker version:

git checkout 1.0.1

The docker-compose.yml file is pre-configured to run the latest image. To run a specific version, adjust your docker-compose.override.yml file to include the image: line, like so:

version: '3.4'
services:
  netbox:
    image: netboxcommunity/netbox:v3.1.3
  netbox-worker:
    image: netboxcommunity/netbox:v3.1.3
  netbox-housekeeping:
    image: netboxcommunity/netbox:v3.1.3

Note that you need to also override the netbox-worker and netbox-housekeeping service definitions to match.

Now pull the Docker image: docker compose pull netbox

Alternative via VERSION variable

To quickly iterate through specific version, you can set the VERSION environment variable.

Make sure that your docker-compose.override.yml does not override the image: line. Or, if you had to built a custom image due to plugin requirements, re-build that first. Now set and export the environment-variable VERSION before invoking docker compose, as shown below. VERSION may be set to the name of any tag of the netboxcommunity/netbox Docker image on Docker Hub or Quay.io.

export VERSION=v2.7.1
docker compose pull netbox
docker compose up -d

Example upgrading to a specific version

Scenario

You're logging into netbox and get a message saying

New Release Available
[NetBox v4.3.2](https://github.com/netbox-community/netbox/releases/tag/v4.3.2) is available. 
    Upgrade Instructions

You check your running versions in the lower left corner.

• In recent versions, both the version of netbox and netbox-docker are displayed
• in older versions you'll only see the version of netbox

Example string: NetBox Community v4.3.0-Docker-3.2.1

Investigate the double dependencies

You want to upgrade in steps - for example:

• Coming from netbox-docker 3.2.0 running netbox 4.2.0
• Targeting netbox 4.3.2 as in the upgrade notice
• You'll look at the the releases and docker hub tags, you see that netbox 4.3.2 is in the latest release along with netbox-docker 3.3.0
• You look at the netbox requirements and see that your postgresql version (17) is fine as they only require a recent one (14)

why? You don't always need to proceed as carefully, but there might be very breaking changes; additionally plugins have different compatibility constraints and this gives you a good chance not ending up in hard to solve situations. a typical 'edge case' would be if a plugin breaks your startup also breaks, meaning some database conversions may fail, meaning you will not successfully get to the next version because your database schema will not fit the expected state. basically you can play it safe or you can learn a lot about netbox, the netbox database schema, database migration scripts and loading backups during startup, all in a very short time frame.

(supposedly safe) Solution:

• Run a database backup with a name that tells you the netbox version
• change branch from netbox-docker 3.2.0 to 3.2.1 (you'll see the VERSION file increment)
• optionally rebuild your image **if you had added some plugins and dependencies ** using FROM netboxcommunity/netbox:v4.2.3-3.2.1
• if the newest netbox-docker minor release supports the newest netbox minor you can jump with both at the same time - 4.2.0->4.2.3, 3.2.0->3.2.1
• start and test
• then upgrade netbox to the last version supported in netbox-docker 3.2.1, which was 4.3.0
• optionally (as above) rebuild your image using FROM netboxcommunity/netbox:v4.3.0-3.2.1
• start and test
• change branch to netbox-docker 3.3.3
• optionally (as above) rebuild your image using FROM netboxcommunity/netbox:v4.3.2-3.3.0
• start and test
• Run a database backup with a name that tells you the new netbox version

In the UI the version string might need a full reload of the page to update.