1# Upgrading to a New NetBox Release
2
3## Review the Release Notes
4
5Prior to upgrading your NetBox instance, be sure to carefully review all [release notes](../release-notes/index.md) that have been published since your current version was released. Although the upgrade process typically does not involve additional work, certain releases may introduce breaking or backward-incompatible changes. These are called out in the release notes under the release in which the change went into effect.
6
7## Update Dependencies to Required Versions
8
9NetBox v3.0 and later requires the following:
10
11| Dependency | Minimum Version |
12|------------|-----------------|
13| Python     | 3.7             |
14| PostgreSQL | 9.6             |
15| Redis      | 4.0             |
16
17## Install the Latest Release
18
19As with the initial installation, you can upgrade NetBox by either downloading the latest release package or by cloning the `master` branch of the git repository.
20
21### Option A: Download a Release
22
23Download the [latest stable release](https://github.com/netbox-community/netbox/releases) from GitHub as a tarball or ZIP archive. Extract it to your desired path. In this example, we'll use `/opt/netbox`.
24
25Download and extract the latest version:
26
27```no-highlight
28wget https://github.com/netbox-community/netbox/archive/vX.Y.Z.tar.gz
29sudo tar -xzf vX.Y.Z.tar.gz -C /opt
30sudo ln -sfn /opt/netbox-X.Y.Z/ /opt/netbox
31```
32
33Copy `local_requirements.txt`, `configuration.py`, and `ldap_config.py` (if present) from the current installation to the new version:
34
35```no-highlight
36sudo cp /opt/netbox-X.Y.Z/local_requirements.txt /opt/netbox/
37sudo cp /opt/netbox-X.Y.Z/netbox/netbox/configuration.py /opt/netbox/netbox/netbox/
38sudo cp /opt/netbox-X.Y.Z/netbox/netbox/ldap_config.py /opt/netbox/netbox/netbox/
39```
40
41Be sure to replicate your uploaded media as well. (The exact action necessary will depend on where you choose to store your media, but in general moving or copying the media directory will suffice.)
42
43```no-highlight
44sudo cp -pr /opt/netbox-X.Y.Z/netbox/media/ /opt/netbox/netbox/
45```
46
47Also make sure to copy or link any custom scripts and reports that you've made. Note that if these are stored outside the project root, you will not need to copy them. (Check the `SCRIPTS_ROOT` and `REPORTS_ROOT` parameters in the configuration file above if you're unsure.)
48
49```no-highlight
50sudo cp -r /opt/netbox-X.Y.Z/netbox/scripts /opt/netbox/netbox/
51sudo cp -r /opt/netbox-X.Y.Z/netbox/reports /opt/netbox/netbox/
52```
53
54If you followed the original installation guide to set up gunicorn, be sure to copy its configuration as well:
55
56```no-highlight
57sudo cp /opt/netbox-X.Y.Z/gunicorn.py /opt/netbox/
58```
59
60### Option B: Clone the Git Repository
61
62This guide assumes that NetBox is installed at `/opt/netbox`. Pull down the most recent iteration of the master branch:
63
64```no-highlight
65cd /opt/netbox
66sudo git checkout master
67sudo git pull origin master
68```
69
70## Run the Upgrade Script
71
72Once the new code is in place, verify that any optional Python packages required by your deployment (e.g. `napalm` or `django-auth-ldap`) are listed in `local_requirements.txt`. Then, run the upgrade script:
73
74```no-highlight
75sudo ./upgrade.sh
76```
77
78!!! warning
79    If the default version of Python is not at least 3.7, you'll need to pass the path to a supported Python version as an environment variable when calling the upgrade script. For example:
80
81    ```no-highlight
82    sudo PYTHON=/usr/bin/python3.7 ./upgrade.sh
83    ```
84
85This script performs the following actions:
86
87* Destroys and rebuilds the Python virtual environment
88* Installs all required Python packages (listed in `requirements.txt`)
89* Installs any additional packages from `local_requirements.txt`
90* Applies any database migrations that were included in the release
91* Builds the documentation locally (for offline use)
92* Collects all static files to be served by the HTTP service
93* Deletes stale content types from the database
94* Deletes all expired user sessions from the database
95
96!!! note
97    If the upgrade script prompts a warning about unreflected database migrations, this indicates that some change has
98    been made to your local codebase and should be investigated. Never attempt to create new migrations unless you are
99    intentionally modifying the database schema.
100
101## Restart the NetBox Services
102
103!!! warning
104    If you are upgrading from an installation that does not use a Python virtual environment (any release prior to v2.7.9), you'll need to update the systemd service files to reference the new Python and gunicorn executables before restarting the services. These are located in `/opt/netbox/venv/bin/`. See the example service files in `/opt/netbox/contrib/` for reference.
105
106Finally, restart the gunicorn and RQ services:
107
108```no-highlight
109sudo systemctl restart netbox netbox-rq
110```
111
112## Verify Housekeeping Scheduling
113
114If upgrading from a release prior to NetBox v3.0, check that a cron task (or similar scheduled process) has been configured to run NetBox's nightly housekeeping command. A shell script which invokes this command is included at `contrib/netbox-housekeeping.sh`. It can be linked from your system's daily cron task directory, or included within the crontab directly. (If NetBox has been installed in a nonstandard path, be sure to update the system paths within this script first.)
115
116```shell
117sudo ln -s /opt/netbox/contrib/netbox-housekeeping.sh /etc/cron.daily/netbox-housekeeping
118```
119
120See the [housekeeping documentation](../administration/housekeeping.md) for further details.
121