Install the Python SDK

Install the arc-tsdb-client package from PyPI, the Python versions it supports, and the optional extras that add pandas, polars, and PyArrow support to the client.

How to install the Arc Python SDK and its optional dependencies.

Requirements

Python 3.9+ (3.10+ recommended for best performance)
Arc server running and accessible

Basic installation

Install the core SDK with pip:

pip install arc-tsdb-client

This installs the minimal dependencies needed to connect to Arc and write/query data using JSON responses.

Core dependencies:

httpx - HTTP client with connection pooling
msgpack - Binary serialization for high-performance writes

Optional dependencies

The SDK supports optional extras for DataFrame integration:

pandas support

For query_pandas() and write_dataframe() with pandas:

pip install arc-tsdb-client[pandas]

What it adds:

pandas - DataFrame library
pyarrow - Required for efficient Arrow-to-pandas conversion

Use when: You're working in Jupyter notebooks, data science workflows, or need pandas DataFrames.

Polars support

For query_polars() with the high-performance Polars library:

pip install arc-tsdb-client[polars]

What it adds:

polars - Fast DataFrame library written in Rust
pyarrow - Required for Arrow IPC parsing

Use when: You need maximum query performance, are processing large datasets, or prefer Polars' API.

All dependencies

Install everything for full functionality:

pip install arc-tsdb-client[all]

What it adds:

pandas
polars
pyarrow

Use when: You want access to all features without worrying about which extras you need.

Using uv (recommended)

uv is a fast Python package manager. Install the SDK with:

# Core only
uv add arc-tsdb-client

# With pandas
uv add arc-tsdb-client --extra pandas

# With all extras
uv add arc-tsdb-client --extra all

Verifying installation

Test that the SDK is installed correctly:

import os
from arc_client import ArcClient, AsyncArcClient

ARC_TOKEN = os.environ["ARC_TOKEN"]

# Check version
import arc_client
print(f"arc-tsdb-client version: {arc_client.__version__}")

# Test connection
with ArcClient(host="localhost", token=os.environ["ARC_TOKEN"]) as client:
    health = client.health()
    print(f"Server status: {health.status}")

Configuration

Basic client setup

import os
from arc_client import ArcClient

ARC_TOKEN = os.environ["ARC_TOKEN"]

client = ArcClient(
    host="localhost",       # Arc server hostname
    port=8000,              # Arc server port (default: 8000)
    token=os.environ["ARC_TOKEN"],     # API token (required)
    database="default",     # Default database for queries
    timeout=30.0,           # Request timeout in seconds
    compression=True,       # Enable gzip compression for writes
    ssl=False,              # Use HTTPS instead of HTTP
    verify_ssl=True,        # Verify SSL certificates
)

Environment variables

You can also configure the client using environment variables:

export ARC_HOST="localhost"
export ARC_PORT="8000"
export ARC_TOKEN="your-token"
export ARC_DATABASE="default"

import os

ARC_TOKEN = os.environ["ARC_TOKEN"]
from arc_client import ArcClient

client = ArcClient(
    host=os.getenv("ARC_HOST", "localhost"),
    port=int(os.getenv("ARC_PORT", "8000")),
    token=os.getenv("ARC_TOKEN"),
    database=os.getenv("ARC_DATABASE", "default"),
)

Context manager (recommended)

Always use the client as a context manager to ensure proper connection cleanup:

import os

ARC_TOKEN = os.environ["ARC_TOKEN"]

# Sync client
with ArcClient(host="localhost", token=os.environ["ARC_TOKEN"]) as client:
    # Use client...
    pass
# Connection automatically closed

# Async client
async with AsyncArcClient(host="localhost", token=os.environ["ARC_TOKEN"]) as client:
    # Use client...
    pass
# Connection automatically closed

Manual connection management

If you can't use a context manager:

import os

ARC_TOKEN = os.environ["ARC_TOKEN"]

client = ArcClient(host="localhost", token=os.environ["ARC_TOKEN"])
try:
    # Use client...
    pass
finally:
    client.close()

Troubleshooting

ImportError: No module named 'pandas'

You need to install the pandas extra:

pip install arc-tsdb-client[pandas]

ImportError: No module named 'polars'

You need to install the polars extra:

pip install arc-tsdb-client[polars]

Connection refused

Make sure Arc is running and accessible:

curl http://localhost:8000/health

Authentication failed

Verify your token is correct:

import os

ARC_TOKEN = os.environ["ARC_TOKEN"]

with ArcClient(host="localhost", token=os.environ["ARC_TOKEN"]) as client:
    result = client.auth.verify()
    if result.valid:
        print(f"Token is valid: {result.token_info.name}")
    else:
        print("Token is invalid")

Next steps

Data Ingestion - Learn how to write data to Arc
Querying - Query data and work with DataFrames
Data Management - Manage retention, CQs, and more

On this page