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

# Install the SDK

> The plugin installs the plurai SDK for you; install it yourself, add extras, and check that the plugin can use it.

You normally don't install the SDK yourself. The first Plurai command checks your project for it, and when it is
missing it asks once and installs the exact version the plugin was tested with into the environment your agent runs
in. This page is for installing it by hand, adding extras, and checking the install.

## Requirements

* Python 3.12 or 3.13, on macOS, Linux or Windows.
* On Windows, an agent driven through Claude's command-line tool (`claude_agent_sdk`) is not supported. Run it on macOS, Linux or WSL.

The SDK is published on PyPI as `plurai-simulation-sdk`. The import name and the command lines are `plurai`.

## What the plugin installs

When no usable SDK is found, the plugin installs it into your project's environment. It looks for that environment
in this order:

1. The activated virtual environment, or the active conda environment (never conda's `base`).
2. A virtual environment in the project folder.
3. The environment poetry (`poetry.lock`) or pipenv (`Pipfile`) names.

An environment activated for another project is skipped when your project has a venv of its own. When the plugin
finds no environment for a Python project, it asks whether to use one you activate or to create `.venv`. A new
`.venv` lacks your agent's dependencies. It never creates `.venv` without asking, and it stops when the
environment's Python is older than 3.12.

## Install it yourself

Every plugin release is tested with one SDK version. Print the exact install line for yours:

```bash theme={null}
python3 <plugin root>/scripts/resolve_plurai.py --install-line
```

It prints, for example:

```bash theme={null}
pip install "plurai-simulation-sdk==1.0.0"
```

Run it in your agent's environment, with the installer that matches your project:

```bash pip (active venv) theme={null}
pip install "plurai-simulation-sdk==1.0.0"
```

```bash repo .venv theme={null}
.venv/bin/pip install "plurai-simulation-sdk==1.0.0"
```

```bash uv venv theme={null}
uv pip install "plurai-simulation-sdk==1.0.0"
```

```bash no venv (CLI on PATH) theme={null}
uv tool install "plurai-simulation-sdk==1.0.0"
```

You can also ask your coding agent: "Install the Plurai SDK into my agent's venv."

## Required version

The plugin runs only the SDK version it was tested with. When the SDK in your environment is a different version,
the plugin stops before a Run, with one line naming the version it found, the version it needs, and the install
command.

The plugin only runs a `plurai` that an installed `plurai-simulation-sdk` distribution provides: a hand-built wrapper
script is not handed your login.

## Extras

The base install is small. Install an extra only when you use it, with the same version pin, for example
`"plurai-simulation-sdk[langfuse]==1.0.0"`. The plugin installs the extras a command needs when it needs them.

| Extra | Adds | Install it when |
| - | - | - |
| `readers` | Document readers (`.docx`, `.pptx`, `.xlsx`, `.pdf`) | Your harness previews documents your agent produces. |
| `extract` | Client-side corpus extraction | You build a [knowledge base](https://docs.plurai.ai/guides/knowledge-base.md) with `plurai ingest-corpus`. |
| `extract-pdf`, `extract-http`, `extract-vertex`, `extract-bigquery`, `extract-redshift`, `extract-azure-sql`, `extract-databricks`, `extract-snowflake`, `extract-bedrock` | The driver for one corpus source kind | Your knowledge base reads from that source. |
| `langsmith` | `langsmith` | You read traces from, or record Runs to, LangSmith. |
| `langfuse` | `langfuse` (4.x) | You read traces from, or record Runs to, Langfuse. |
| `arize` | `arize`, `arize-otel`, OpenInference conventions | You record Runs to Arize. |
| `braintrust` | `braintrust` | You record Runs to Braintrust. |
| `anonymize` | Presidio analyzer and anonymizer | Your workspace's anonymization posture is `anonymized` (`anonymize: true` in `plurai.config.yaml`). |
| `anonymize-binary` | Presidio image redactor, `pdf2image`, `Pillow` | Your posture is `anonymized` and you upload images or PDFs. |

`plurai login`, `plurai --version` and `plurai capabilities` need none of the extras.

### Anonymization extras

The `anonymize` extra also needs a spaCy English model, which is not a Python dependency:

```bash theme={null}
python -m spacy download en_core_web_lg   # en_core_web_md or en_core_web_sm also work
```

The `anonymize-binary` extra also needs two system programs on `PATH`: Tesseract (`brew install tesseract`, or
`tesseract-ocr`) and Poppler (`brew install poppler`, or `poppler-utils`).

Under the `anonymized` posture, ingestion fails closed: without the extra, the model or the system programs, it
refuses to run rather than upload unscrubbed data. A workspace on the default `raw` posture needs none of them.
See [Data and privacy](https://docs.plurai.ai/security/data-and-privacy.md).

## Verify the install

```bash theme={null}
plurai --version          # plurai 1.0.0
plurai --identity         # which build is running (commit or content hash)
plurai capabilities       # this build's commands and features, as JSON
plurai login --status     # the backend, organization and user you are signed in as
```

`plurai capabilities` is what the plugin reads. Its `commands` list is read off the live CLI, and its `features`
name behavior that command names do not reveal, such as `export-dir-traces`. `plurai login --status` never prints
your key.

## Agent and runner in different environments

The runner (`plurai-run-simulation`) and your agent can use different virtual environments, for example when
your agent pins dependencies the runner's environment cannot share. The agent runs in a child interpreter: the
runner's own Python by default, or the one `PLURAI_CHILD_PYTHON` names:

```bash theme={null}
export PLURAI_CHILD_PYTHON=/path/to/agent-venv/bin/python
```

The agent's environment must have the SDK installed too, because `simulate.py` imports `plurai`.

## Upgrade

When you update the plugin, the next Plurai command finds the SDK at the old version and offers to install the new
one. To do it yourself, run the line `--install-line` prints. Check the [changelog](https://docs.plurai.ai/sdk/changelog.md) for breaking
changes first.

## Next steps

> [card] [Run simulations](https://docs.plurai.ai/sdk/run-simulations.md)
>
> Use `plurai-run-simulation` directly.

> [card] [CLI reference](https://docs.plurai.ai/sdk/cli.md)
>
> Every `plurai` command and flag.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.