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
Check and unpack the new bundle exactly as in Install step 1 (
sha256sum -c,tar -xzf,./netos-install verify).Preflight with your existing
site.yml:cd /root/netos/netos-bundle-<new release>-*/ sudo ./netos-install preflight --site /root/netos/site.ymlupgrade_compatiblemust bePASS, showing the release you have now, for exampleinstalled=2026.10.0-rc1.current_pluginslists the installed versions.Upgrade, in
tmuxor as a transient unit (see Install step 4 for why):sudo ./netos-install upgrade --site /root/netos/site.yml --yesIt 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.
Check:
sudo ./netos-install status --site /root/netos/site.ymlIt 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:
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 --yesThis removes the
# BEGIN netos-installblock fromconfiguration.py(a copy is kept next to it asconfiguration.py.netos-disabled), moves any Netos lines out oflocal_requirements.txt, and restarts NetBox.Upgrade NetBox by your usual procedure.
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
disableremoved the block, NetBox served normally with no plugins and all 176 Netos tables kept, and a followinginstallput 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.