Install & Compatibility
Where this runs
tested against v7.8.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.392s · 22.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.3s · import 0.368s · 23MB
21MB installed
● package 21MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Api
✓ from pynetbox import Api
✗ import pynetbox
nb = pynetbox.api(...)
This quickstart demonstrates how to establish a connection to a NetBox instance using `pynetbox`, retrieve the NetBox version, and fetch a list of devices. Ensure `NETBOX_URL` and `NETBOX_TOKEN` environment variables are set or replaced in the code.
import os
import pynetbox
NETBOX_URL = os.environ.get('NETBOX_URL', 'http://localhost:8000')
NETBOX_TOKEN = os.environ.get('NETBOX_TOKEN', 'YOUR_API_TOKEN_HERE') # Required for write operations
try:
nb = pynetbox.api(NETBOX_URL, token=NETBOX_TOKEN)
# Test connection and fetch NetBox version
print(f"Connected to NetBox version: {nb.version}")
# Fetch the first 5 devices
devices = list(nb.dcim.devices.all()[:5])
if devices:
print("\nFirst 5 Devices:")
for device in devices:
print(f" - {device.name} (ID: {device.id})")
else:
print("\nNo devices found.")
except pynetbox.RequestError as e:
print(f"NetBox API Request Error: {e}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Debug
Known issues
breakingIn pynetbox v7.6.0, the `ObjectChange` model was moved to the `core` module for NetBox 4.1.0+ compatibility. Code referencing `nb.extras.object_changes` must be updated to `nb.core.object_changes`.fixUpdate import paths for ObjectChange: `nb.extras.object_changes` becomes `nb.core.object_changes`.
affects: >=7.6.0
breakingpynetbox v7.4.0 dropped support for Python 3.8 and 3.9, aligning with NetBox 4.0's removal of support for these Python versions. Users on older Python versions must upgrade.fixUpgrade Python environment to 3.10 or higher. NetBox documentation recommends Python 3.10+.
affects: >=7.4.0
gotchaNetBox's API, by default, silently returns *all* objects if an invalid filter is provided, which can lead to unexpected and incorrect results. `pynetbox` offers `strict_filters=True` in the API constructor to enable client-side validation and raise an exception for invalid filters.fixInstantiate the API with `nb = pynetbox.api(url, token, strict_filters=True)` to enforce filter validation.
affects: All versions
gotchaBetween pynetbox v7.0.0 and v7.3.x, there was a bug (#597) that caused failures when attempting to insert complex custom fields (e.g., lists of dictionaries). The `update()` method would return successfully, but the fields would be set to `None` in NetBox. This was fixed in v7.4.0.fixUpgrade pynetbox to v7.4.0 or newer if encountering issues with complex custom field updates.
affects: 7.0.0 - 7.3.x
gotchapynetbox versions 6.7 and later require NetBox 3.3 or higher. Ensure your NetBox instance meets this minimum version to avoid compatibility issues.fixVerify NetBox version meets or exceeds 3.3.0 when using pynetbox 6.7.0+.
affects: 6.7.0 - Current
gotchaNetBox v4.5 introduced v2 API tokens, which `pynetbox` v7.6.0+ supports. While legacy tokens still work, using v2 tokens might require updating your token management strategy for enhanced security features.fixConsider generating new v2 API tokens in NetBox 4.5+ and updating scripts to use them, or ensure legacy tokens are managed securely (e.g., with expiration).
affects: >=7.6.0 (with NetBox >=4.5)
Upgrade
Version history
7.8.0latest on PyPI · released Jun 18, 2026
Audit
Dependencies
requestsrequiredHandles HTTP communication.
packagingrequiredFor version parsing and comparisons.