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.0.0 and higher.
  • Databases supported: PostgreSQL, MySQL

Note

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

System Dependencies for PDF Export

The Reports app includes the ability to download reports as PDF files. This functionality requires WeasyPrint, which depends on several system libraries that must be installed on your system.

DOCX and HTML downloads need no system libraries

Downloading a report as Word (DOCX) or HTML is pure-Python — DOCX uses html-for-docx (imported as html4docx), installed automatically with the app. Only PDF requires the WeasyPrint system packages below.

Required for PDF Downloads

To use the PDF download feature, install the following system packages before installing the Python dependencies. Without these packages, PDF download attempts will return an error message indicating that PDF export is not available on that installation. HTML export will continue to work normally.

Debian/Ubuntu

Install the system dependencies required by WeasyPrint:

sudo apt-get update && sudo apt-get install -y \
    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 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 WeasyPrint system dependencies for PDF generation
RUN apt-get update && apt-get install --no-install-recommends -y \
    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

HTML Export Still Works

If you cannot install these system dependencies, you can still use the HTML export feature. Only PDF generation requires WeasyPrint and its dependencies.

Install Guide

Note

Apps can be installed from the Python Package Index or locally. See the Nautobot documentation for more details. The pip package name for this app is nautobot-reports.

The app is available as a Python package via PyPI and can be installed with pip:

pip install nautobot-reports

WeasyPrint Included

The nautobot-reports package includes WeasyPrint as a dependency for PDF generation. WeasyPrint requires system libraries to be installed first (see System Dependencies for PDF Export above). If these system libraries are not installed, the app will still function for HTML and other exports, but PDF downloads will display a user-friendly error message.

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

PDF Export Not Working

If PDF download attempts show an error message stating "PDF export is not available on this installation," the WeasyPrint system dependencies are missing.

Symptoms:

  • PDF download returns a 500 error with message: "PDF export is not available on this installation"
  • Nautobot logs contain: "PDF export unavailable: weasyprint is not installed"

Solution:

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

Testing WeasyPrint Installation:

You can verify WeasyPrint is working correctly:

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

# Test WeasyPrint import
python -c "import weasyprint; print('WeasyPrint OK')"

If this command fails, the system dependencies are not properly installed.

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