Installation

Install and configure the Infrahub Python SDK in your environment

The Infrahub Python SDK can be installed using pip, uv, or other Python package managers.

Requirements

The SDK requires Python 3.12 or higher. Ensure you have a compatible Python version installed.

python --version  # Should be 3.12 or higher

Installation Methods

Using pip

The simplest way to install the SDK:

pip install infrahub-sdk

Using uv (Recommended)

For faster dependency resolution and installation:

uv pip install infrahub-sdk

Using Poetry

Add to your pyproject.toml:

[tool.poetry.dependencies]
infrahub-sdk = "^1.7.6"

Then install:

poetry install

Development Installation

To install from source for development:

git clone https://github.com/opsmill/infrahub.git
cd infrahub/python_sdk
uv pip install -e .

Verify Installation

Confirm the SDK is installed correctly:

import infrahub_sdk

print(infrahub_sdk.__version__)

Or check the installed package:

pip show infrahub-sdk

Configuration

Environment Variables

The SDK can be configured using environment variables:

export INFRAHUB_ADDRESS="http://localhost:8000"
export INFRAHUB_API_TOKEN="your-api-token"

Available Environment Variables

Variable	Description	Default
INFRAHUB_ADDRESS	URL of your Infrahub instance	http://localhost:8000
INFRAHUB_API_TOKEN	API authentication token	None
INFRAHUB_TIMEOUT	Request timeout in seconds	30
INFRAHUB_LOG_LEVEL	Logging level (DEBUG, INFO, WARNING, ERROR)	INFO

Configuration File

Create a infrahub.toml configuration file:

[infrahub]
address = "http://localhost:8000"
api_token = "your-api-token"
timeout = 30

Place this file in:

• Current directory: ./infrahub.toml
• User config: ~/.config/infrahub/infrahub.toml
• System config: /etc/infrahub/infrahub.toml

Programmatic Configuration

Configure directly in your code:

from infrahub_sdk import Config, InfrahubClient

config = Config(
    address="http://localhost:8000",
    api_token="your-api-token",
    timeout=30
)

client = InfrahubClient(config=config)

Dependencies

The SDK automatically installs these core dependencies:

• Pydantic (>=2.12,<2.13): Data validation
• httpx: Async HTTP client
• Rich (>=13,<14): Terminal formatting
• PyArrow (>=14): Data serialization
• GraphQL: API integration

Optional Dependencies

Testing Dependencies

For running tests with the SDK:

pip install infrahub-sdk[test]

Includes:

• pytest
• pytest-asyncio
• pytest-httpx

Development Dependencies

For SDK development:

pip install infrahub-sdk[dev]

Includes:

• mypy (type checking)
• ruff (linting)
• black (formatting)

Docker Integration

Use the SDK in a Docker container:

FROM python:3.12-slim

RUN pip install infrahub-sdk

COPY your_script.py /app/
WORKDIR /app

CMD ["python", "your_script.py"]

Testing the Connection

Create a simple test script:

test_connection.py

import asyncio
from infrahub_sdk import InfrahubClient

async def test_connection():
    client = InfrahubClient()
    
    # Test basic connectivity
    try:
        # Fetch schema to verify connection
        await client.schema.fetch()
        print("✓ Successfully connected to Infrahub")
    except Exception as e:
        print(f"✗ Connection failed: {e}")

if __name__ == "__main__":
    asyncio.run(test_connection())

Run the test:

python test_connection.py

Troubleshooting

ImportError: No module named 'infrahub_sdk'

Ensure the SDK is installed in your active Python environment:

pip list | grep infrahub-sdk

If not listed, reinstall the package.

Connection refused or timeout errors

Verify your Infrahub instance is running and accessible:

curl http://localhost:8000/api/

Check your INFRAHUB_ADDRESS environment variable or configuration.

Python version incompatibility

The SDK requires Python 3.12+. Check your version:

python --version

Use a version manager like pyenv to install Python 3.12:

pyenv install 3.12
pyenv local 3.12

SSL certificate verification errors

For development environments with self-signed certificates:

from infrahub_sdk import Config, InfrahubClient

config = Config(
    address="https://localhost:8000",
    tls_insecure=True  # Only for development!
)
client = InfrahubClient(config=config)

Next Steps

Quickstart

Build your first application with the SDK

Client Setup

Learn about client configuration options