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

# Installation

> Learn how to install the SDK and set up your environment

> [!WARNING]
>
> You are reading the docs of Galtea 5.13. [Read this page in the latest version](https://docs.galtea.ai/sdk/installation.md).

To install the Galtea Python SDK, use the following command:

```bash theme={"system"}
pip install galtea
```

For more information, visit the [Galtea PyPI page](https://pypi.org/project/galtea/).

### Requirements

Ensure you have the following prerequisites:

* Python 3.10 or higher
* pip (Python package installer)

### Setting Up Your Environment

1. **Create a Virtual Environment** (optional but recommended):

```bash theme={"system"}
python -m venv venv
source venv/bin/activate  # On Windows use `venv\Scripts\activate`
```

2. **Install the SDK**:

```bash theme={"system"}
pip install galtea
```

3. **Verify Installation** — initialize the client to confirm the SDK is working:

```python theme={"system"}
from galtea import Galtea

# Verify the SDK is properly installed by initializing it
# Note: Replace "YOUR_API_KEY" with your actual API key from the Galtea dashboard
galtea = Galtea(api_key="YOUR_API_KEY")
print("Galtea SDK installed successfully!")
```

### Custom API URL and headers

By default, the SDK calls `https://api.galtea.ai`. When your network reaches Galtea through an API gateway, set
the gateway URL and the extra headers the gateway needs. The SDK sends those headers on every request to the Galtea
API, including the span exports. File uploads and downloads do not carry them yet.

Pass them to the `Galtea` constructor:

```python theme={"system"}
galtea = Galtea(
    api_key="YOUR_API_KEY",
    base_url=os.environ["GALTEA_API_URL"],  # for example, your API gateway URL
    headers={"X-IBM-Client-Id": "YOUR_CLIENT_ID"},
)
```

* `base_url`: the API URL to call.
* `headers`: a dictionary of header names to string values.

Or set them once as environment variables:

```bash theme={"system"}
export GALTEA_API_URL="https://your-gateway.example.com/galtea"
export GALTEA_EXTRA_HEADERS='{"X-IBM-Client-Id": "your-client-id", "X-IBM-Client-Secret": "your-client-secret"}'
```

* `GALTEA_API_URL`: the API URL to call.
* `GALTEA_EXTRA_HEADERS`: a JSON object of header names to string values. Every value must be a string.

A constructor argument wins over its environment variable. When you pass `headers`, the SDK ignores
`GALTEA_EXTRA_HEADERS` completely and does not merge the two.

> [!NOTE]
>
> The SDK always sets `Authorization` (your API key, as `Bearer gsk_...`), `User-Agent`, `Content-Type`,
> `Content-Length` and `Host` itself. A configured header with one of these names, in any letter case, is ignored
> with a warning that names the header. If `GALTEA_EXTRA_HEADERS` is not a JSON object of
> strings, a header name is not a valid HTTP name (for example it has a space), two names differ only in letter
> case, or a header value has a line break, leading whitespace or a non-Latin-1 character, `Galtea()` raises a
> `ValueError` that does not show the value. A `GALTEA_EXTRA_HEADERS` that holds only spaces counts as unset. A redirect that changes the host, the scheme or the
> port drops the extra headers. A subdomain is another host. A redirect from http to https on the default ports keeps them.

### Upgrading the SDK

To upgrade to the latest version of the Galtea SDK, use the following command:

```bash theme={"system"}
pip install --upgrade galtea
```

> [!WARNING]
>
> **Upgrading from 4.x to 5.0.0 changes names your code uses.** `galtea.tests` becomes
> `galtea.datasets`, and `galtea.traces` now means one input and one output rather than one step
> inside it. Read [Dataset, Trace, and Span Renames](https://docs.galtea.ai/v5.13/sdk/migration-guides/entity-renames.md) before
> you upgrade: some old calls keep running against a different entity instead of failing.

### Troubleshooting

If you encounter any issues during installation, contact our support team at [support@galtea.ai](mailto:support@galtea.ai).


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