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.
• 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()

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

    # Query all tags
    tags = await client.all(kind="BuiltinTag")
    for tag in tags:
        print(f"{tag.name.value} — {tag.description.value}")


asyncio.run(main())

Sync

from infrahub_sdk import InfrahubClientSync

client = InfrahubClientSync()

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

# Query all tags
tags = client.all(kind="BuiltinTag")
for tag in tags:
    print(f"{tag.name.value} — {tag.description.value}")

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 queries by hand	client.get(), client.all(), client.filters()
Mutations	Construct and POST GraphQL mutations	node.save(), node.delete()
Concurrency	Roll your own async batching	Built-in batch with concurrency control
Typing	Maintain type definitions manually	Schema-driven type export using protocols

tip

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.
• 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.

Video walkthrough

Installation

uv

uv add infrahub-sdk

Extras are available for additional functionality:

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

pip

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

Installation guide/python-sdk/guides/installation

Next steps

• Hello world example — Your first client connection and query.
• 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.