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

# ci.deps

> Check installed extras and fail fast on missing ones.

Report which optional extras (`torch`, `tensorflow`, `pandas`,
`datasets`, SQL drivers, ...) are installed, and, when called with
required names, raise `CirronDependencyError` listing every missing
dep at once with a combined `pip install` command.

Use it at the top of a long training script so a missing extra raises
immediately instead of 40 minutes into training with a cryptic
`ImportError`, or inside library code that wraps the SDK and wants to
gate on what's present.

`ci.deps()` is the in-process equivalent of the [`cirron doctor` CLI](/cli/commands/doctor),
which inspects an installed `cirron-sdk` from outside the Python
process. Both read from the same `pyproject.toml` extras list.

## Signature

```python theme={null}
def deps(*required: str) -> dict[str, str | None]
```

## Parameters

| Name        | Type  | Purpose                                                                    |
| ----------- | ----- | -------------------------------------------------------------------------- |
| `*required` | `str` | Optional. Names of extras that must be present. Raises if any are missing. |

Each `required` name can be either the **import name** (`"torch"`,
`"datasets"`, `"sklearn"`) or the **pyproject extras name**
(`"hf"` for `datasets`). Unknown names raise `ValueError`: that's a
caller bug, not a missing dep.

## Returns

A dict keyed by import name. With no arguments, one entry for every
known extra, mapping to the installed version string or `None`. With
required names, only the requested entries (all present; missing
ones would have raised).

## Behavior

* **Zero import cost**: uses `importlib.util.find_spec` +
  `importlib.metadata.version`, not `__import__`. Heavy frameworks
  (torch, tensorflow, transformers) are never actually loaded by the
  check itself. Cheap to call at module import time.
* **Fail-fast form lists every miss at once**: one
  `CirronDependencyError` with every missing dep in the body and a
  combined `pip install 'cirron-sdk[a,b,c]'` command, rather than one
  error per missing dep.
* **Caller bug vs missing dep**: unknown extras names raise
  `ValueError`, not `CirronDependencyError`. Catching
  `CirronDependencyError` never hides a typo in your code.

## Examples

### Report every extra

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

deps = ci.deps()
# {
#   'pandas': '2.3.3', 'polars': None, 'torch': '2.6.0',
#   'tensorflow': None, 'transformers': '4.41.0', 'datasets': None,
#   'sklearn': '1.5.0', 'safetensors': '0.4.3',
#   'boto3': None, 'psycopg': None, ...
# }
```

Keyed by import name so `deps["polars"]` reads naturally. Extras
whose pyproject name differs from the import name (`hf` → `datasets`,
`sklearn` → `scikit-learn`) show up under the import name.

### Fail fast at script startup

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

ci.deps("torch", "pandas", "transformers")

# If transformers (say) isn't installed:
#
# CirronDependencyError: Missing required dependencies:
#   - transformers: pip install 'cirron-sdk[transformers]'
#
# If multiple are missing, the combined install command is also shown:
#
# CirronDependencyError: Missing required dependencies:
#   - torch: pip install 'cirron-sdk[torch]'
#   - pandas: pip install 'cirron-sdk[pandas]'
#   - transformers: pip install 'cirron-sdk[transformers]'
# Or install all together: pip install 'cirron-sdk[pandas,torch,transformers]'
```

### Guard optional code paths

```python theme={null}
deps = ci.deps()

if deps["polars"]:
    df = ci.load("./data.parquet", as_="polars")
else:
    df = ci.load("./data.parquet")   # pandas fallback
```

### Accept both import and extras names

```python theme={null}
# Equivalent: "hf" is the pyproject extras name, "datasets" is the import name.
ci.deps("hf")
ci.deps("datasets")
```

### From a `Cirron` instance

Module-level `ci.deps` is sugar over the default instance; the method
exists on `Cirron` for API symmetry with the other surface.

```python theme={null}
from cirron import Cirron

c = Cirron()
report = c.deps()                    # same output as ci.deps()
c.deps("torch", "pandas")            # same fail-fast semantics
```

Extras presence is process-global, so which instance you call on
doesn't change what the probe sees.

## When a check returns `"unknown"`

If a module is importable but not pip-tracked (e.g. an editable install
with no metadata, or a vendored copy), `ci.deps()` reports
`"unknown"` instead of a version string. The extra is considered
**present**, and `ci.deps(name)` does not raise.

## What it does not do

* **Does not install anything.** The error message names the pip
  command; the user runs it.
* **Does not probe the Cirron platform.** Fully local.
* **Does not validate config.** For that, see [`ci.profile().health()`](/sdk/reference/lifecycle#health).

## Related

<CardGroup cols={2}>
  <Card title="cirron doctor" icon="stethoscope" href="/cli/commands/doctor">
    External CLI equivalent. Inspects an installed `cirron-sdk` from
    outside the Python process.
  </Card>

  <Card title="CirronDependencyError" icon="triangle-exclamation" href="/sdk/errors#cirrondependencyerror">
    Exception raised by the fail-fast form.
  </Card>

  <Card title="Installation" icon="download" href="/sdk/installation">
    The full list of extras and what they add.
  </Card>

  <Card title="Profile lifecycle" icon="play" href="/sdk/reference/lifecycle">
    `profiler.health()` for runtime state.
  </Card>
</CardGroup>