Infrahub Python SDK

The Infrahub Python SDK is a client library for interacting with Infrahub programmatically. It handles authentication, query construction, and data serialization so you can work with infrastructure data using native Python objects instead of raw API calls.

What you can do with it

The SDK covers three main use cases:

• Automate inside Infrahub — Write transforms, generators, and checks that run as part of Infrahub's pipeline.
• Integrate with external systems — Query and sync data between Infrahub and your existing tools, scripts, or CI/CD pipelines.
• Build custom applications — Use Infrahub as a data backend for your own Python projects.

Under the hood, tools like infrahubctl and the Infrahub Ansible collection both use this SDK.

A quick look

Async

import asyncio
from infrahub_sdk import InfrahubClient

async def main():
    client = InfrahubClient()

    # Query all devices
    devices = await client.all(kind="InfraDevice")
    for device in devices:
        print(f"{device.name.value} — {device.site.peer.name.value}")

    # Create a new tag and save it
    tag = await client.create(kind="BuiltinTag", name="staging")
    await tag.save()

    # Work on a branch
    branch = await client.branch.create("update-tags", description="Add staging tags")

asyncio.run(main())

Sync

from infrahub_sdk import InfrahubClientSync

client = InfrahubClientSync()

# Query all devices
devices = client.all(kind="InfraDevice")
for device in devices:
    print(f"{device.name.value} — {device.site.peer.name.value}")

# Create a new tag and save it
tag = client.create(kind="BuiltinTag", name="staging")
tag.save()

# Work on a branch
branch = client.branch.create("update-tags", description="Add staging tags")

Both async and sync clients expose the same API. Choose async for applications that benefit from concurrent I/O (transforms, large-scale sync scripts) and sync for straightforward scripting.

Why use the SDK over direct API calls

Concern	Raw API	SDK
Authentication	Manual token management, JWT refresh	Handled automatically
Querying	Build GraphQL strings by hand	client.get(), client.all(), client.filters()
Mutations	Construct and POST GraphQL mutations	node.save(), node.delete()
Relationships	Navigate nested JSON responses	Access via node.relationship.peer
Branching	Manage branch headers/parameters	client.branch.create(), client.branch.merge()
Concurrency	Roll your own async batching	Built-in batch with concurrency control
Schema awareness	Parse schema separately	Schema-driven filters and validation

The SDK removes the boilerplate so you can focus on the logic that matters to your infrastructure.

Key capabilities

• CRUD operations — Create, read, update, and delete any node type defined in your schema.
• Filtering — Query nodes using schema-aware attribute and relationship filters (name__value, site__name__value, etc.).
• Branch management — Create, merge, rebase, and diff branches programmatically.
• Batch execution — Group multiple queries into a batch with configurable concurrency limits.
• Tracking — Tag operations with identifiers for auditing and idempotent updates.
• Store — Cache retrieved nodes locally to reduce redundant queries.
• GraphQL escape hatch — Run arbitrary GraphQL queries when the high-level API doesn't cover your use case.

Installation

pip install infrahub-sdk

Extras are available for additional functionality:

pip install 'infrahub-sdk[ctl]'    # Adds the infrahubctl CLI
pip install 'infrahub-sdk[tests]'  # Adds the testing framework for transforms and checks
pip install 'infrahub-sdk[all]'    # Everything

See the installation guide for details.

Next steps

• Create and configure a client — Set up authentication, proxy settings, and client options.
• Query data — Retrieve nodes with filters and GraphQL.
• Create, update, and delete nodes — Manage infrastructure data programmatically.
• Work with branches — Use Infrahub's branch workflow from Python.
• Batch operations — Optimize performance for bulk operations.
• Client configuration reference — All available configuration options.