Upgrading

There are two kinds of upgrade. They are different procedures.

You are upgrading Procedure
Netos only: a newer bundle for the same NetBox version Netos upgrade below. One command.
NetBox itself (with Netos installed) NetBox upgrade with Netos. Three steps.

Every bundle is complete: it carries every Netos plugin and every dependency. You can go from any release listed in the new bundle's manifest.json under previous_compatible straight to the new one; skipping releases costs nothing.

Netos upgrade

  1. Check and unpack the new bundle exactly as in Install step 1 (sha256sum -c, tar -xzf, ./netos-install verify).

  2. Preflight with your existing site.yml:

    cd /root/netos/netos-bundle-<new release>-*/
    sudo ./netos-install preflight --site /root/netos/site.yml
    

    upgrade_compatible must be PASS, showing the release you have now, for example installed=2026.10.0-rc1. current_plugins lists the installed versions.

  3. Upgrade, in tmux or as a transient unit (see Install step 4 for why):

    sudo ./netos-install upgrade --site /root/netos/site.yml --yes
    

    It runs the same steps as install: preflight, stop NetBox, snapshot, packages, configuration block, migrations, start, post-check, receipt. On the test host an upgrade from 2026.10.0-rc1 to 2026.10.0-rc2 took 6 minutes.

  4. Check:

    sudo ./netos-install status --site /root/netos/site.yml
    

    It must show the new release and PASS.

Your data survives an upgrade. On the test host a NetBox site, five devices and a Netos notification group created before the upgrade were all present, unchanged, afterwards.

If the upgrade fails, or the new release misbehaves, see Roll back. Rolling back an upgrade returns you to the previous Netos release with the data as it was when the upgrade started.

NetBox upgrade with Netos

NetBox's own upgrade.sh rebuilds the venv and runs migrations with every configured plugin enabled. A rebuilt venv has no Netos packages, so NetBox would fail to start them. It also installs local_requirements.txt from PyPI, which fails offline. So Netos steps aside first:

  1. Take Netos out of NetBox's plugin list. Netos tables and data stay in the database untouched:

    sudo ./netos-install disable --site /root/netos/site.yml --yes
    

    This removes the # BEGIN netos-install block from configuration.py (a copy is kept next to it as configuration.py.netos-disabled), moves any Netos lines out of local_requirements.txt, and restarts NetBox.

  2. Upgrade NetBox by your usual procedure.

  3. Install the Netos bundle built for the new NetBox version (the file name says which, for example ...-netbox4.5.10-...). This re-adds the block and runs the Netos migrations:

    sudo ./netos-install install --site /root/netos/site.yml --yes
    

Status of this procedure: on the test host disable removed the block, NetBox served normally with no plugins and all 176 Netos tables kept, and a following install put Netos back in 5 minutes. A NetBox version upgrade between two bundles has not been run end to end yet, because only NetBox 4.5.10 bundles exist. Ask Netos before your first NetBox upgrade.