Pynetbox

Python API client library for NetBox.

Note: Version 6.7 and later of the library only supports NetBox 3.3 and above.

Compatibility

Each pyNetBox Version listed below has been tested with its corresponding NetBox Version.

NetBox Version	Plugin Version
4.7	7.9.0
4.6	7.8.0
4.6	7.7.0
4.5	7.6.1
4.5	7.6.0
4.4	7.5.0
4.3	7.5.0
4.2	7.5.0
4.1	7.5.0
4.0.6	7.4.1
4.0.0	7.3.4
3.7	7.3.0
3.6	7.2.0
3.5	7.1.0
3.3	7.0.0

Installation

To install run pip install pynetbox.

Alternatively, you can clone the repo and run pip install ..

Quick Start

The full pynetbox API is documented on GitHub Pages, but the following should be enough to get started using it.

To begin, import pynetbox and instantiate the API.

import pynetbox
nb = pynetbox.api(
    'http://localhost:8000',
    token='d6f4e314a5b5fefd164995169f28ae32d987704f'
)

The first argument the .api() method takes is the NetBox URL. There are a handful of named arguments you can provide, but in most cases none are required to simply pull data. In order to write, the token argument should to be provided.

Queries

The pynetbox API is setup so that NetBox's apps are attributes of the .api() object, and in turn those apps have attribute representing each endpoint. Each endpoint has a handful of methods available to carry out actions on the endpoint. For example, in order to query all the objects in the devices endpoint you would do the following:

>>> devices = nb.dcim.devices.all()
>>> for device in devices:
...     print(device.name)
...
test1-leaf1
test1-leaf2
test1-leaf3
>>>

Note that the all() and filter() methods are generators and return an object that can be iterated over only once. If you are going to be iterating over it repeatedly you need to either call the all() method again, or encapsulate the results in a list object like this:

>>> devices = list(nb.dcim.devices.all())

Threading

pynetbox supports multithreaded calls for .filter() and .all() queries. It is highly recommended you have MAX_PAGE_SIZE in your Netbox install set to anything except 0 or None. The default value of 1000 is usually a good value to use. To enable threading, add threading=True parameter to the .api:

nb = pynetbox.api(
    'http://localhost:8000',
    threading=True,
)

Filters validation

NetBox doesn't validate filters passed to the GET API endpoints, which are accessed with .get() and .filter(). If a filter is incorrect, NetBox silently returns the entire database table content. Pynetbox allows to check provided parameters against NetBox OpenAPI specification before doing the call, and raise an exception if a parameter is incorrect.

This can be enabled globally by setting strict_filters=True in the API object initialization:

nb = pynetbox.api(
    'http://localhost:8000',
    strict_filters=True,
)

This can also be enabled and disabled on a per-request basis:

# Disable for one request when enabled globally.
# Will not raise an exception and return the entire Device table.
nb.dcim.devices.filter(non_existing_filter="aaaa", strict_filters=False)

# Enable for one request when not enabled globally.
# Will raise an exception.
nb.dcim.devices.filter(non_existing_filter="aaaa", strict_filters=True)

Running Tests

First, create and activate a Python virtual environment in the pynetbox directory to isolate the project dependencies:

python3 -m venv venv
source venv/bin/activate

Install pynetbox with its development dependencies:

pip install -e ".[dev]"

Unit tests mock every HTTP response and need no external services:

pytest tests --ignore=tests/integration

Integration tests run against real NetBox instances. They require Docker to be installed and running, as they download and launch netbox-docker containers during the run:

pytest tests/integration --netbox-versions 4.6

Before opening a pull request, run the lint gate the same way CI does:

pre-commit run --all-files

Metadata

Release files for pynetbox 7.9.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pynetbox 7.9.0
File	Size	Uploaded
pynetbox-7.9.0.tar.gz	149.2 kB	Oct 8, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for pynetbox 7.9.0
File	Interpreter	ABI	Platform	Reset
pynetbox-7.9.0-py3-none-any.whl 56.1 kB Oct 8, 2026	Python 3	none	any	Details

Total release size: 205.3 kB

Release files / pynetbox-7.9.0.tar.gz

Download URL	pynetbox-7.9.0.tar.gz
Size	149.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`a50e5caa07df1795a9706e5262a864cf371ae63592585191c1ad361d42695d8b`
BLAKE2b-256 checksum How to use checksums	`58669156cd3486c9017be6923e2e44e01110a85dcdfdf7a03558aadbaf4ffc4d`
Upload date	Oct 8, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.13`

Release files / pynetbox-7.9.0-py3-none-any.whl

Download URL	pynetbox-7.9.0-py3-none-any.whl
Size	56.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`f0bc3c07f71ae9d564f14b37111fc749084601ed98d5c3c1ec8e94a08810892f`
BLAKE2b-256 checksum How to use checksums	`4fce7dbb8a2ec85161af46d2004f8669f8ae22eb133c7b45247aa884a62f16ae`
Upload date	Oct 8, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.13`