Skip to content

Installing Nautobot

This section of the documentation discusses installing and configuring the Nautobot application itself.

These instructions will guide you through the following actions:

  • Establish a Nautobot root directory for the application environment
  • Create a nautobot system account
  • Create a Python virtual environment (virtualenv)
  • Install Nautobot and all required Python packages
  • Run the database schema migrations
  • Aggregate static resource files on disk
  • Verify the installation using the development/test server


Your database server and Redis must have been successfully installed before continuing with deployment steps. If you haven't done that yet, please visit the guide on Installing Nautobot Dependencies


You need to select a directory path where everything related to Nautobot will be installed. We will use this value across the documentation and it will be referred to as NAUTOBOT_ROOT.

We will be using this path as the home directory of the nautobot user.


We have selected /opt/nautobot, but you may use any directory you choose.

Later on, we will need to set this directory path as the NAUTOBOT_ROOT environment variable to tell Nautobot where to find its files and settings.

Create the Nautobot System User

Create a system user account named nautobot. This user will own all of the Nautobot files, and the Nautobot web services will be configured to run under this account.

The following command also creates the /opt/nautobot directory and sets it as the home directory for the user.

sudo useradd --system --shell /bin/bash --create-home --home-dir /opt/nautobot nautobot

Setup the Virtual Environment

A Python virtual environment or virtualenv is like a container for a set of Python packages. A virtualenv allows you to build environments suited to specific projects without interfering with system packages or other projects.

When installed per the documentation, Nautobot uses a virtual environment in production.

In the following steps, we will have you create the virtualenv within the NAUTOBOT_ROOT you chose in the previous step. This is the same we had you set as the home directory as the nautobot user.


Instead of deliberately requiring you to activate/deactivate the virtualenv, we are emphasizing on relying on the $PATH to access programs installed within it. We find this to be much more intuitive and natural when working with Nautobot in this way.

Create the Virtual Environment

As root, we're going to create the virtualenv in our NAUTOBOT_ROOT as the nautobot user to populate the /opt/nautobot directory with a self-contained Python environment including a bin directory for scripts and a lib directory for Python libraries.

sudo -u nautobot python3 -m venv /opt/nautobot
sudo -u nautobot python3.8 -m venv /opt/nautobot

Update the Nautobot .bashrc

So what about the NAUTOBOT_ROOT? We've referenced this environment variable several times. Here is where it finally gets set.

We need to set the NAUTOBOT_ROOT environment variable for the nautobot user and make sure that it always set without having to do it manually.

Run this command to update ~/.bashrc for nautobot so that anytime you become nautobot, your NAUTOBOT_ROOT will be set automatically.

echo "export NAUTOBOT_ROOT=/opt/nautobot" | sudo tee -a ~nautobot/.bashrc

Sudo to nautobot

It is critical to install Nautobot as the nautobot user so that we don't have to worry about fixing permissions later.

sudo -iu nautobot

Observe also that you can now echo the value of the NAUTOBOT_ROOT environment variable that is automatically set because we added to .bashrc:


Example output:



Unless explicitly stated, all remaining steps requiring the use of pip3 or nautobot-server in this document should be performed as the nautobot user!

Understanding the Virtual Environment

Because the nautobot user was created with NAUTOBOT_ROOT set as its home directory and we had you set the shell to /bin/bash, the binary path $NAUTOBOT_ROOT/bin is automatically added to the beginning of the $PATH environment variable:

echo $PATH

Example output:

echo $PATH

Example output:


Therefore, any commands executed by the nautobot user will always check $NAUTOBOT_ROOT/bin first.

Since NAUTOBOT_ROOT also contains the Python virtualenv for Nautobot, all of the commands you will execute as the nautobot user, will automatically prefer the virtualenv's commands because they come first in the $PATH.

As the nautobot user, you may use which pip3 to confirm that you are using the correct version of pip3. The path should match that of $NAUTOBOT_ROOT/bin. For example:

which pip3

Example output:


This makes sure that the version of Python you're using, as well any dependencies that you install, remain isolated in this environment.

Prepare the Virtual Environment

Before we install anything into the virtualenv, we want to make sure that Pip is running the latest version.

Pip is Python's package installer and is referred interchangeably as pip or pip3. For the purpose of this document, we'll deliberately be referring to it as pip3. Many common issues can be solved by running the latest version of Pip. Before continuing with installing Nautobot, upgrade Pip to its latest release.

We also want to deliberately install the wheel library which will tell Pip to always try to install wheel packages if they are available. A wheel is a pre-compiled Python package, which is quicker and safer to install because it does not require development libraries or gcc to be installed on your system just so that some more advanced Python libraries can be compiled.

pip3 install --upgrade pip wheel

Install Nautobot

Use Pip to install Nautobot:

pip3 install nautobot

Use Pip to install Nautobot with the MySQL client:

pip3 install "nautobot[mysql]"

Great! We have NAUTOBOT_ROOT ready for use by the nautobot user, so let's proceed to verifying the installation.

Verify your Nautobot Installation

You should now have a fancy nautobot-server command in your environment. This will be your gateway to all things Nautobot! Run it to confirm the installed version of nautobot:

nautobot-server --version


Before you can use Nautobot, you'll need to configure it by telling it where your database and Redis servers can be found, among other things. This is done with the configuration file.

Initialize your configuration

Initialize a new configuration by running nautobot-server init. You may specify an alternate location and detailed instructions for this are covered in the documentation on Nautobot Configuration.

However, because we've set the NAUTOBOT_ROOT, this command will automatically create a new at the default location based on this at $NAUTOBOT_ROOT/

nautobot-server init

Example output:

Nautobot would like to send anonymized installation metrics to the project's maintainers.
These metrics include the installed Nautobot version, the Python version in use, an anonymous "deployment ID", and a list of one-way-hashed names of enabled Nautobot Apps and their versions.
Allow Nautobot to send these metrics? [y/n]: y
Installation metrics will be sent when running 'nautobot-server post_upgrade'. Thank you!
Configuration file created at /opt/nautobot/

Added in version 1.6.0

The nautobot-server init command will now prompt you to set the initial value for the INSTALLATION_METRICS_ENABLED setting. See the send_installation_metrics command for more information about the feature that this setting toggles.

Required Settings

Your provides sane defaults for all of the configuration settings. You will inevitably need to update the settings for your environment, most notably the DATABASES setting. If you do not wish to modify the config, by default, many of these configuration settings can also be specified by environment variables. Please see Required Settings for further details.

Edit $NAUTOBOT_ROOT/, and head over to the documentation on Required Settings to tweak your required settings. At a minimum, you'll need to update the following settings:

  • ALLOWED_HOSTS: You must set this value. This can be set to ["*"] for a quick start, but this value is not suitable for production deployment.
  • DATABASES: Database connection parameters. If you installed your database server on the same system as Nautobot, you'll need to update the USER and PASSWORD fields here. If you are using MySQL, you'll also need to update the ENGINE field, changing the default database driver suffix from django.db.backends.postgresql to django.db.backends.mysql.
  • Redis settings: Redis configuration requires multiple settings, if different from the defaults. If you installed Redis on the same system as Nautobot, you do not need to change these settings.


You absolutely must update your required settings in your or Nautobot will not work.


If you are using MySQL as your database backend, you must also update the database ENGINE setting to django.db.backends.mysql.

Save your changes to your and then proceed to the next step.

MySQL Unicode Settings

If you are using MySQL as your database backend, and you want to enable support for Unicode emojis, please make sure to add "OPTIONS": {"charset": "utf8mb4"} to your DATABASES setting. Please see the configuration guide on MySQL Unicode settings for more information.

Optional Settings

All Python packages required by Nautobot will be installed automatically when running pip3 install nautobot.

Nautobot also supports the ability to install optional Python packages. If desired, these packages should be listed in local_requirements.txt within the NAUTOBOT_ROOT directory, such as /opt/nautobot/local_requirements.txt.

If you decide to use any Nautobot plugins, they should be listed in this file.

We will cover two examples of common optional settings below.

Configuring NAPALM

Nautobot provides built-in support for the NAPALM automation library, which allows Nautobot to fetch live data from devices and return it to a requester via its REST API. The NAPALM_USERNAME and NAPALM_PASSWORD configuration parameters define the credentials to be used when connecting to a device.

To use NAPALM, add nautobot[napalm] to your local_requirements.txt so that it can be installed and kept up to date:

echo "nautobot[napalm]" >> $NAUTOBOT_ROOT/local_requirements.txt

Remote File Storage

By default, Nautobot will use the local filesystem to store uploaded files. To use a remote filesystem, install the django-storages library and configure your desired storage backend in

To use remote file storage, add nautobot[remote_storage] to your local_requirements.txt so that it can be installed and kept up to date:

echo "nautobot[remote_storage]" >> $NAUTOBOT_ROOT/local_requirements.txt

An example of using django-storages with AWS S3 buckets, visit the django-storages with S3 user-guide.

Prepare the Database

Before Nautobot can run, the database migrations must be performed to prepare the database for use. This will populate the database tables and relationships:

nautobot-server migrate

Create a Superuser

Nautobot does not come with any predefined user accounts. You'll need to create a administrative superuser account to be able to log into Nautobot for the first time. Specifying an email address for the user is not required, but be sure to use a very strong password.

nautobot-server createsuperuser

Build Nautobot 2.0 UI

Nautobot 2.0 introduces a new user interface. This interface is built using React and requires Node.js version 18 or higher to build the UI.

Build the UI

Nautobot provides a management command to install the required Node.js packages and build the UI:

nautobot-server build_ui --npm-install

This only needs to be performed manually the first time Nautobot v2 is installed. The post_upgrade command that must be ran after any Nautobot upgrade will automatically re-run this command.

Create Static Directories

Nautobot relies upon many static files including:

Each of these have their own corresponding setting that defined in, but by default they will all be placed in NAUTOBOT_ROOT unless you tell Nautobot otherwise by customizing their unique variable.

The collectstatic command will create these directories if they do not exist, and in the case of the static files directory, it will also copy the appropriate files:

nautobot-server collectstatic

Install Local Requirements


If you did not create a local_requirements.txt above, please skip this step.

This step is entirely optional. As indicated above, we mentioned that any extra local requirements should go into $NAUTOBOT_ROOT/local_requirements.txt.

pip3 install -r $NAUTOBOT_ROOT/local_requirements.txt

Check your Configuration

Nautobot leverages Django's built-in system check framework to validate the configuration to detect common problems and to provide hints for how to fix them.

Checks are ran automatically when running a development server using nautobot-server runserver, but not when running in production using WSGI.


Get into the habit of running checks before deployments!

nautobot-server check

Test the Application

At this point, we should be able to run Nautobot's development server for testing. We can check by starting a development instance:

nautobot-server runserver --insecure

Next, connect to the name or IP of the server (as defined in ALLOWED_HOSTS) on port 8080; for example, You should be greeted with the Nautobot home page.


DO NOT USE THIS SERVER IN A PRODUCTION SETTING. The development server is for development and testing purposes only. It is neither performant nor secure enough for production use.


If the test service does not run, or you cannot reach the Nautobot home page, something has gone wrong. Do not proceed with the rest of this guide until the installation has been corrected. Some platforms (such as CentOS) have a firewall enabled by default. If you are unable to connect to the server url on port 8080, verify the firewall policy to allow the appropriate connections, or select an already permitted port.


Certain Nautobot features (Git repository synchronization, webhooks, jobs, etc.) depend on the presence of Nautobot's background Celery worker process, which is not automatically started by the runserver command. To start it for testing purposes, you can run nautobot-server celery worker separately. For production use, Nautobot and the worker processes should be managed by systemd rather than started manually, as described in the next section of this documentation.

Note that the initial user interface will be locked down for non-authenticated users.

Nautobot UI as seen by a non-authenticated user

Try logging in using the superuser account we just created. Once authenticated, you'll be able to access all areas of the UI:

Nautobot UI as seen by an administrator

Type Ctrl-C to stop the development server. Now you're ready to proceed to starting Nautobot as a system service.