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

# Install

> Install ToraDB from PyPI or build from source

ToraDB is published on [PyPI](https://pypi.org/project/toradb/) as the `toradb` package (prebuilt wheels for macOS, Linux, and Windows). Use **pip** for normal use; build from source only when you are developing ToraDB itself.

## Install from PyPI

<Steps>
  <Step title="Create a virtual environment (recommended)">
    ```bash theme={null}
    python3 -m venv .venv
    source .venv/bin/activate   # Windows: .venv\Scripts\activate
    pip install --upgrade pip
    ```
  </Step>

  <Step title="Install ToraDB">
    ```bash theme={null}
    pip install toradb
    ```

    Optional extras:

    ```bash theme={null}
    pip install "toradb[embeddings]"   # sentence-transformers
    pip install "toradb[openai]"       # OpenAI embeddings client
    ```
  </Step>

  <Step title="Verify installation">
    ```bash theme={null}
    python -c "import toradb; print('toradb import ok')"
    toradb smoke
    ```
  </Step>
</Steps>

## Build from source

Use this path when you need unreleased changes or you are contributing to the Rust/Python codebase.

### Prerequisites

* Rust stable toolchain (`rustup`, `cargo`)
* Python 3.8+
* `pip`
* `maturin` (for building the Python extension)

The repo pins Rust to stable via `rust-toolchain.toml`.

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/sophatvathana/toradb.git toradb
    cd toradb
    ```
  </Step>

  <Step title="Build the Rust workspace">
    ```bash theme={null}
    cargo build
    ```
  </Step>

  <Step title="Create a Python virtual environment">
    ```bash theme={null}
    python3 -m venv .venv
    source .venv/bin/activate
    pip install --upgrade pip
    pip install maturin
    ```
  </Step>

  <Step title="Install the ToraDB Python package">
    From the repo root:

    ```bash theme={null}
    maturin develop
    ```
  </Step>

  <Step title="Verify installation">
    ```bash theme={null}
    python -c "import toradb; print('toradb import ok')"
    toradb smoke
    ```
  </Step>
</Steps>

## Run tests

Rust tests (source tree only):

```bash theme={null}
cargo test
```

Python smoke tests:

```bash theme={null}
pytest tests/python_smoke.py -q
```

## Optional benchmark

```bash theme={null}
cargo bench -p toradb-storage --bench segment_read
```

## Troubleshooting

* If `pip install toradb` fails on an unsupported platform, try [build from source](#build-from-source) on that machine.
* If `maturin develop` fails, confirm the virtual environment is activated.
* If Python cannot import `toradb` after a source build, rerun `maturin develop`.
* If the `toradb` command is not found, ensure the venv `bin` directory is on your `PATH` (activation usually handles this).


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