{"id":4712,"library":"pynetbox","title":"NetBox API Client Library","description":"pynetbox is the official Python API client library for NetBox, a popular open-source IPAM and DCIM solution. It provides a convenient, object-oriented interface for interacting with the NetBox REST API, abstracting away the complexities of raw HTTP requests. The library is actively maintained with frequent releases, currently at version 7.6.1, ensuring compatibility with the latest NetBox versions (supporting NetBox 3.3+ and recent 4.x features like v2 API tokens).","status":"active","version":"7.6.1","language":"en","source_language":"en","source_url":"https://github.com/netbox-community/pynetbox","tags":["NetBox","API Client","Network Automation","DCIM","IPAM","Infrastructure as Code"],"install":[{"cmd":"pip install pynetbox","lang":"bash","label":"Install pynetbox"}],"dependencies":[{"reason":"Handles HTTP communication.","package":"requests","optional":false},{"reason":"For version parsing and comparisons.","package":"packaging","optional":false}],"imports":[{"note":"The primary entry point to interact with the NetBox API.","symbol":"api","correct":"import pynetbox\nnb = pynetbox.api(...)"}],"quickstart":{"code":"import os\nimport pynetbox\n\nNETBOX_URL = os.environ.get('NETBOX_URL', 'http://localhost:8000')\nNETBOX_TOKEN = os.environ.get('NETBOX_TOKEN', 'YOUR_API_TOKEN_HERE') # Required for write operations\n\ntry:\n    nb = pynetbox.api(NETBOX_URL, token=NETBOX_TOKEN)\n    \n    # Test connection and fetch NetBox version\n    print(f\"Connected to NetBox version: {nb.version}\")\n\n    # Fetch the first 5 devices\n    devices = list(nb.dcim.devices.all()[:5])\n    if devices:\n        print(\"\\nFirst 5 Devices:\")\n        for device in devices:\n            print(f\"  - {device.name} (ID: {device.id})\")\n    else:\n        print(\"\\nNo devices found.\")\n\nexcept pynetbox.RequestError as e:\n    print(f\"NetBox API Request Error: {e}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Update import paths for ObjectChange: `nb.extras.object_changes` becomes `nb.core.object_changes`.","message":"In 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`.","severity":"breaking","affected_versions":">=7.6.0"},{"fix":"Upgrade Python environment to 3.10 or higher. NetBox documentation recommends Python 3.10+.","message":"pynetbox 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.","severity":"breaking","affected_versions":">=7.4.0"},{"fix":"Instantiate the API with `nb = pynetbox.api(url, token, strict_filters=True)` to enforce filter validation.","message":"NetBox'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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade pynetbox to v7.4.0 or newer if encountering issues with complex custom field updates.","message":"Between 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.","severity":"gotcha","affected_versions":"7.0.0 - 7.3.x"},{"fix":"Verify NetBox version meets or exceeds 3.3.0 when using pynetbox 6.7.0+.","message":"pynetbox versions 6.7 and later require NetBox 3.3 or higher. Ensure your NetBox instance meets this minimum version to avoid compatibility issues.","severity":"gotcha","affected_versions":"6.7.0 - Current"},{"fix":"Consider 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).","message":"NetBox 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.","severity":"gotcha","affected_versions":">=7.6.0 (with NetBox >=4.5)"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}