Skip to content

Installing the App in Nautobot

Here you will find detailed instructions on how to install and configure the App within your Nautobot environment.

Prerequisites

  • The app is compatible with Nautobot 3.2.0 and higher.
  • Databases supported: PostgreSQL, MySQL

Note

Please check the dedicated page for a full compatibility matrix and the deprecation policy.

Required System Dependencies

The app requires native system libraries that cannot be installed by pip. Install them before installing the Python dependencies — without them, Nautobot will fail to start with the app enabled.

  • cairo — published reports embed all images directly in the report document, and SVG images are converted to PNG as part of that step (DOCX files cannot contain SVG). The conversion uses CairoSVG, which loads cairo when the app is imported.
  • Pango and HarfBuzz — PDF downloads are generated with WeasyPrint, which renders text through these libraries and likewise loads them when the app is imported.

Debian/Ubuntu

sudo apt-get update && sudo apt-get install -y \
    libcairo2 \
    libpango-1.0-0 \
    libpangoft2-1.0-0 \
    libharfbuzz-subset0

For additional font support in Debian/Ubuntu, you can optionally install:

sudo apt-get install -y fonts-dejavu-core fonts-noto-core

RHEL/Fedora Linux

sudo dnf install -y cairo pango

For additional font support in RHEL/Fedora, you can optionally install:

sudo dnf install -y dejavu-sans-fonts \
    dejavu-sans-mono-fonts \
    dejavu-serif-fonts

Docker Installation

If you're running Nautobot in Docker, add these dependencies to your Dockerfile before installing the Python requirements:

# Install cairo (SVG conversion) and WeasyPrint (PDF generation) system dependencies
RUN apt-get update && apt-get install --no-install-recommends -y \
    libcairo2 \
    libpango-1.0-0 \
    libpangoft2-1.0-0 \
    libharfbuzz-subset0 && \
    rm -rf /var/lib/apt/lists/*

For additional font support in Docker, add to the install above:

fonts-dejavu-core \
fonts-noto-core

Install Guide

The app is distributed as a Python package (nautobot-reports) which can be installed by Python package managers (e.g. pip, poetry, uv etc.) from an authorized private repository.

Important

Nautobot Reports is commercial (licensed) software. To obtain access to the Network To Code private package repository, please contact us through the customer portal. Then review the instructions on how to set up the repository in your Python package manager of choice.

pip install nautobot-reports

WeasyPrint and CairoSVG Included

The nautobot-reports package includes WeasyPrint (PDF generation) and CairoSVG (SVG image conversion) as Python dependencies, but both need their system libraries installed first (see Required System Dependencies above). Nautobot will not start with the app enabled while those libraries are missing.

To ensure Reports is automatically re-installed during future upgrades, create a file named local_requirements.txt (if not already existing) in the Nautobot root directory (alongside requirements.txt) and list the nautobot-reports package:

echo nautobot-reports >> local_requirements.txt

Once installed, the app needs to be enabled in your Nautobot configuration. The following block of code below shows the additional configuration required to be added to your nautobot_config.py file:

  • Append "nautobot_reports" to the PLUGINS list.
  • Append the "nautobot_reports" dictionary to the PLUGINS_CONFIG dictionary and override any defaults.
  • Configure Django's email backend if you want to use the email functionality of the app.
# In your nautobot_config.py
PLUGINS = ["nautobot_reports"]

PLUGINS_CONFIG = {
    "nautobot_reports": {
        # ADD YOUR SETTINGS HERE
    },
}

Once the Nautobot configuration is updated, run the Post Upgrade command (nautobot-server post_upgrade) to run migrations and clear any cache:

nautobot-server post_upgrade

Then restart (if necessary) the Nautobot services which may include:

  • Nautobot
  • Nautobot Workers
  • Nautobot Scheduler
sudo systemctl restart nautobot nautobot-worker nautobot-scheduler

App Configuration

The app behavior can be controlled with the following list of settings.

Note

The Reports app does not require any specific plugin configuration settings in PLUGINS_CONFIG. Configuration is done through the Nautobot UI after installation.

Page Size

Generated PDF and DOCX downloads, along with the on-screen preview, share a single page size. Set it from Nautobot's Configuration page (see Administratively Configurable Settings), under the Reports section:

  • Page Size — A4 (default) or Letter. Unrecognized values fall back to A4.

The selected size applies the next time a report is previewed or downloaded.

Email Configuration (Optional)

If you want to use the email functionality of the app (scheduled report delivery), you need to configure Django's email backend in your nautobot_config.py:

# Django email settings example (SMTP)
EMAIL_HOST = "smtp.example.com"
EMAIL_PORT = 587
EMAIL_USE_TLS = True   # STARTTLS on submission port (587)
# For implicit SSL on port 465, use EMAIL_USE_SSL = True INSTEAD of EMAIL_USE_TLS.
EMAIL_HOST_USER = os.environ.get("NAUTOBOT_EMAIL_HOST_USER", "")
EMAIL_HOST_PASSWORD = os.environ.get("NAUTOBOT_EMAIL_HOST_PASSWORD", "")
DEFAULT_FROM_EMAIL = "user@example.com"

# Other EMAIL settings may be required depending on your email provider, such as EMAIL_SSL_CERTFILE, etc.
# EMAIL_SSL_CERTFILE = "/path/to/certfile.pem"
# EMAIL_SSL_KEYFILE = "/path/to/keyfile.pem"
# EMAIL_TIMEOUT = 10  # Timeout in seconds for email operations
# For development without SMTP, swap the backend:
# EMAIL_BACKEND = "django.core.mail.backends.console.EmailBackend"

See Django's email settings reference for the full list of options and supported backends.

Once the Nautobot configuration is updated, run the Post Upgrade command (nautobot-server post_upgrade) to run migrations and clear any cache:

nautobot-server post_upgrade

Then restart (if necessary) the Nautobot services which may include:

  • Nautobot
  • Nautobot Workers
  • Nautobot Scheduler
sudo systemctl restart nautobot nautobot-worker nautobot-scheduler

Object Permissions and Published Reports

Report data is captured with the permissions of the user who publishes the report and frozen into the stored snapshot. Nautobot object permissions are enforced while a report is being built, previewed, and published, but not against the data inside a report after it has been published. See Permissions for the full behavior.

The view permission on Published Report can expose restricted data

Granting the view permission on the Published Report model (nautobot_reports.view_publishedreport) can expose data a user could not otherwise see. A published report contains whatever the publishing user's permissions allowed at publish time, and object permissions are not enforced against the data inside the report when it is viewed or downloaded.

Published Report records themselves have no built-in per-owner scoping: a view permission with no constraints lists every published report, regardless of who published it or whether the viewer can see the source template. If reports may contain sensitive data, add constraints to the Object Permission on Published Report (for example, on published_by or report_template) to limit which snapshots a user can open.

The Publish And Email Report job delivers the same frozen snapshot to the listed email recipients, whose permissions are likewise never consulted.

Troubleshooting

Nautobot Fails to Start After Installing the App

If Nautobot (or one of its workers) fails to start with an ImportError naming cairosvg or weasyprint, the required system libraries are missing.

Symptoms:

  • Startup fails with: "Python package cairosvg failed to load. You may need to install libcairo2 (debian/ubuntu) or cairo (fedora/rhel)."
  • Startup fails with: "Python package weasyprint failed to load. You may need to install libpango-1.0-0, libpangoft2-1.0-0, and libharfbuzz-subset0 (debian/ubuntu) or pango (fedora/rhel)."

Solution:

  1. Install all required system dependencies (see Required System Dependencies)
  2. Restart Nautobot services after installing system packages
  3. Verify the installation with the test command below

Testing the installation:

# Activate your Nautobot virtual environment
source /opt/nautobot/bin/activate

# Both imports must succeed for the app to load
python -c "import cairosvg; import weasyprint; print('OK')"

If this command fails, the system dependencies are not properly installed. The traceback names the library that could not be loaded.

Common Issues

Issue: OSError: cannot load library 'gobject-2.0'

Solution: Install the missing system libraries, particularly libgobject-2.0-0 on Debian/Ubuntu or gobject-introspection on RHEL/Fedora.

Issue: Font rendering problems in PDFs

Solution: Install additional font packages: 

# Debian/Ubuntu
sudo apt-get install fonts-liberation fonts-noto-sans fonts-noto-serif

# RHEL/Fedora
sudo dnf install liberation-fonts