> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cirron.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install the SDK and framework extras (PyTorch, TF, sklearn, inference).

## Requirements

<Info>
  **Python 3.11 or newer.** The SDK uses `tomllib` from the standard
  library.
</Info>

## Core install

```bash theme={null}
pip install cirron-sdk
```

The core install is minimal: no pandas, no polars, no ML framework
dependency. It gives you the profiler, scope tree, marks, loop
wrappers, flush thread + local spool, `@ci.inference`, `ci.env`,
`ci.secret`, and the `Cirron` configuration class.

## Extras

Framework hooks and data-loader backends are opt-in extras so you only
pull what you use.

| Extra          | Adds                                                                  |
| -------------- | --------------------------------------------------------------------- |
| `pandas`       | pandas backend for `ci.load()` (the default return type)              |
| `polars`       | polars backend for `ci.load(as_="polars")`                            |
| `arrow`        | PyArrow, faster Parquet reads for any filesystem source               |
| `hf`           | `datasets.Dataset` return type for `ci.load(as_="hf")`                |
| `torch`        | PyTorch profiling hooks (forward / backward / optimizer / DataLoader) |
| `tensorflow`   | TensorFlow / Keras profiling hooks (Callback-based)                   |
| `transformers` | HuggingFace `Trainer` callback hooks + LLM detectors                  |
| `sklearn`      | Version floor for `ci.wrap()` (`scikit-learn >= 1.3`)                 |
| `image`        | Pillow, image decode for `ci.load()` image sources                    |
| `s3`           | `ci.load("s3://...")` via boto3                                       |
| `gcs`          | `ci.load("gs://...")` via `google-cloud-storage`                      |
| `azure`        | `ci.load("azure://...")` via `azure-storage-blob`                     |
| `postgres`     | `ci.load("postgres://...")`                                           |
| `mysql`        | `ci.load("mysql://...")`                                              |
| `databricks`   | `ci.load("databricks://...")`                                         |
| `snowflake`    | `ci.load("snowflake://...")`                                          |
| `sql`          | All four SQL drivers                                                  |
| `dotenv`       | `python-dotenv`: `.env` loading in `ci.env()`                         |
| `safetensors`  | safetensors reader, inspect snapshot blobs locally                    |
| `all`          | Every extra above                                                     |

<CodeGroup>
  ```bash pip theme={null}
  pip install "cirron-sdk[torch,pandas]"
  pip install "cirron-sdk[transformers]"
  pip install "cirron-sdk[sql]"
  pip install "cirron-sdk[all]"
  ```

  ```bash uv theme={null}
  uv add "cirron-sdk[torch,pandas]"
  uv add "cirron-sdk[transformers]"
  uv add "cirron-sdk[sql]"
  uv add "cirron-sdk[all]"
  ```
</CodeGroup>

Install multiple extras at once by comma-separating them inside the
brackets.

## Authentication

Authentication is optional; the SDK runs standalone without it. To
sync traces to the Cirron platform, set an API key:

```bash theme={null}
export CIRRON_API_KEY=...
export CIRRON_API_ENDPOINT=https://app.cirron.com   # optional; default shown
```

Inside a Cirron pipeline or deployment, the
`CIRRON_RUN_ID` / `CIRRON_PIPELINE_ID` / `CIRRON_DEPLOYMENT_ID` /
`CIRRON_WORKSPACE_ID` context is injected by the runner. You do not
set these yourself.

See [Configuration](/sdk/configuration) for the full resolution order
(explicit args → env vars → `~/.cirron/config.toml` → defaults) and
self-hosted endpoints.

## Verify

```python theme={null}
import cirron as ci

p = ci.profile()
print(p.health())
ci.shutdown()
```

You should see a dict roughly like this (exact keys and values depend
on what's installed and whether you have a `CIRRON_API_KEY` set):

```python theme={null}
{
    "enabled": True,
    "frameworks_installed": [],            # ["torch"] / ["transformers", "torch"] / ...
    "transport": "file_only",              # or "http" / "event_stream"
    "scope_depth": 1,                      # the cirron.session root scope
    "mark_drop_count": 0,
    "spool_drop_count": 0,
    "spool_bytes": 0,
    "flush_latency_ns": 0,                 # 0 on the first call is expected; filled after the first flush
}
```

A file will also appear under `./.cirron/spool/` containing the
`cirron.session` root span.

### Check which extras are installed

`ci.deps()` reports which optional extras the current environment has.
Call it with no arguments for a full report, or with required names to
fail fast at script startup if any are missing:

```python theme={null}
import cirron as ci

# Report everything
ci.deps()
# {'pandas': '2.3.3', 'polars': None, 'torch': '2.6.0', ...}

# Require specific extras. Raises CirronDependencyError with a
# combined pip install command if any are missing.
ci.deps("torch", "pandas")
```

See [`ci.deps`](/sdk/reference/deps) for the full surface.

## Next step

<Card title="Quickstart" icon="bolt" href="/sdk/quickstart">
  Three 5-minute paths: zero-touch training, custom PyTorch loop, and
  inference.
</Card>