Nautobot API Client Library

Common errors

• requests.exceptions.ConnectionError: ('Connection aborted.', ConnectionRefusedError(111, 'Connection refused'))

  cause The Python script cannot establish a connection to the specified Nautobot URL. This could be due to an incorrect URL, the Nautobot service not running, or network/firewall issues.
  fix Verify the `NAUTOBOT_URL` environment variable or the `url` parameter in your `pynautobot.api()` call. Ensure the Nautobot server is running and accessible from the machine running the script. Check firewall rules.

• requests.exceptions.HTTPError: 401 Client Error: Unauthorized for url: https://nautobot.example.com/api/...

  cause The Nautobot API client is attempting to make a request without a valid authentication token, or the provided token has insufficient permissions for the requested action.
  fix Ensure the `NAUTOBOT_TOKEN` environment variable or the `token` parameter in your `pynautobot.api()` call is set correctly with a valid API token. Verify that the token has the necessary read/write permissions for the resources being accessed.

• pynautobot.exceptions.ObjectDoesNotExist: No object found for query: {'slug': 'my-missing-object'}

  cause You are attempting to retrieve a specific object (e.g., using `.get()`) with criteria that do not match any existing object in Nautobot. This often happens with unique fields like 'slug' or 'name'.
  fix Double-check the lookup criteria (e.g., slug, name, ID). If the object might not exist, use `.filter()` which returns an empty list instead of raising an exception if no objects match, or wrap your `.get()` call in a `try...except pynautobot.exceptions.ObjectDoesNotExist` block.

Warnings

• breaking pynautobot v3.x.x is specifically designed for compatibility with Nautobot 3.x.x and later. Using pynautobot v3.x.x with older Nautobot 2.x.x instances will result in API incompatibility errors and unexpected behavior.
  Fix: Ensure your pynautobot version matches your Nautobot instance version: use pynautobot v3.x.x for Nautobot v3.x.x+ and pynautobot v2.x.x (LTM) for Nautobot v2.x.x.
• deprecated pynautobot v2.x.x is now in Long Term Maintenance (LTM) mode, only receiving critical bug and security fixes for Nautobot 2.4. New feature development is exclusively on the pynautobot v3.x.x branch.
  Fix: Upgrade your Nautobot instance to v3.x.x+ and pynautobot to v3.x.x+ to benefit from new features and ongoing development. If stuck on Nautobot 2.x.x, use pynautobot v2.x.x but be aware of limited support.
• gotcha Prior to pynautobot v3.1.0, accessing nested attributes of related objects (e.g., `device.site.name` directly) would often require calling `full_details()` on the parent object first, leading to additional API calls or `AttributeError` if not handled. While v3.1.0 improved this, older code might still make inefficient calls.
  Fix: For pynautobot v3.1.0 and later, nested attributes are often directly accessible without explicit `full_details()`. Review your code to remove unnecessary `full_details()` calls for related objects if upgrading, as they might still trigger extra API requests. If on older versions, be aware of this limitation and use `full_details()` as needed.

Install

• pip install pynautobot Install latest version

Imports

• api
  wrong:

  import pynautobot.api

  correct:

  from pynautobot import api

  The 'api' object is directly exposed at the top level of the pynautobot package for convenience.

Quickstart

This quickstart initializes the pynautobot API client using environment variables for the Nautobot URL and API token. It then fetches and prints the names of the first five devices found in your Nautobot instance. Ensure `NAUTOBOT_URL` and `NAUTOBOT_TOKEN` are set in your environment.

import os
from pynautobot import api

NAUTOBOT_URL = os.environ.get("NAUTOBOT_URL", "https://nautobot.example.com")
NAUTOBOT_TOKEN = os.environ.get("NAUTOBOT_TOKEN", "YOUR_NAUTOBOT_TOKEN_HERE")

if not NAUTOBOT_URL or not NAUTOBOT_TOKEN:
    print("Please set NAUTOBOT_URL and NAUTOBOT_TOKEN environment variables.")
    exit(1)

try:
    # Initialize the pynautobot API client
    nautobot = api(url=NAUTOBOT_URL, token=NAUTOBOT_TOKEN)

    # Fetch all devices
    print(f"Connecting to Nautobot at {NAUTOBOT_URL}...")
    devices = nautobot.dcim.devices.all()

    if devices:
        print(f"Found {len(devices)} devices:")
        for device in devices[:5]: # Print first 5 devices
            print(f"- {device.name} ({device.device_type.model}) in {device.site.name}")
    else:
        print("No devices found.")

    # Example: Create a new tag
    # new_tag = nautobot.extras.tags.create(name="my-new-tag", slug="my-new-tag", description="A tag created by pynautobot")
    # print(f"Created tag: {new_tag.name}")

except Exception as e:
    print(f"An error occurred: {e}")