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

# Version compatibility and upgrades

> Check which Python and dependency versions the HiddenLayer Python SDK supports, understand its versioning policy, and upgrade safely.

This page explains which Python versions and dependencies the HiddenLayer Python SDK supports, how SDK version numbers are assigned, and how to upgrade without surprises. It also lists deprecated features that you should move away from.

The information on this page applies to SDK version 3.10.0.

## Supported Python versions

The SDK requires Python 3.9 or later. The package declares support for these versions:

| Python version | Supported | Notes |
| - | - | - |
| 3.9 | Yes | Minimum supported version. Python 3.9 reached end of life in October 2025 and no longer receives security fixes from the Python project. |
| 3.10 | Yes | |
| 3.11 | Yes | Recommended minimum for new projects. |
| 3.12 | Yes | |
| 3.13 | Yes | |
| 3.14 | Yes | Compatibility fixes were added in SDK 3.2.0. |
| 3.8 and earlier | No | Support for Python 3.8 was dropped in SDK 3.2.0. |

Use Python 3.11 or later for new projects. If you still run Python 3.9, plan to upgrade, because a future SDK release may drop it.

## Dependencies

When you install `hiddenlayer-sdk`, pip installs these dependencies within the following version ranges:

| Package | Supported range | Purpose |
| - | - | - |
| `httpx` | `>=0.23.0, <1` | HTTP client used for all API requests |
| `pydantic` | `>=1.9.0, <3` | Response models. Both Pydantic v1 and v2 are supported. |
| `typing-extensions` | `>=4.14, <5` | Typing features for older Python versions |
| `anyio` | `>=3.5.0, <5` | Async support |
| `distro` | `>=1.7.0, <2` | Platform information sent in request headers |
| `sniffio` | Any | Detects the async library in use |
| `requests` | `>=2.32.4` | Declared dependency |
| `requests-auth` | `>=8.0.0` | Declared dependency |
| `types-requests` | `>=2.32.0.20241016` | Type hints for `requests` |

Because the SDK supports both Pydantic v1 and v2, you can add it to a project that already depends on either version.

The optional `aiohttp` extra (`pip install "hiddenlayer-sdk[aiohttp]"`) adds `aiohttp` and `httpx_aiohttp>=0.1.9` for the async client. The model scanning helpers for S3, Azure Blob Storage, and Hugging Face need packages that you install separately. See [Installation](/docs/integrations/sdk_python/installation).

## Versioning policy

The SDK generally follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html) (SemVer). In a version number such as `3.11.0`, the parts are `MAJOR.MINOR.PATCH`:

* **Major** releases can include breaking changes.
* **Minor** releases add features in a backwards-compatible way.
* **Patch** releases fix bugs.

According to the SDK's README, some backwards-incompatible changes may be released as minor versions:

1. Changes that only affect static types, without breaking runtime behavior.
2. Changes to library internals that are technically public but not intended or documented for external use.
3. Changes that are not expected to impact the vast majority of users in practice.

In practice, this means a minor upgrade can occasionally cause type-checker errors or affect code that uses undocumented internals. Test before you upgrade in production.

### Beta APIs

Some HiddenLayer APIs are in beta, meaning they are not yet generally available (GA) or production ready. You can use them in production at your own risk. For beta APIs:

* HiddenLayer does not provide compatibility guarantees. Breaking changes can happen at any time.
* SDK functions and types associated with beta APIs are excluded when determining SemVer versions. A minor or patch release can change them.

When you call a beta endpoint, the SDK emits a `hiddenlayer.BetaWarning`. In version 3.11.0, this applies to:

* `client.runtime.evaluate_request`, `evaluate_response`, and `evaluate_interaction`
* All `client.evaluations.red_team` methods, including calls made by `client.evaluation_sessions.red_team`

For details, see the [Beta API guidelines](https://dev.hiddenlayer.ai/docs/beta-api-faq) on the developer portal. To handle the warning in code, see [Error handling](/docs/integrations/sdk_python/error_handling#beta-warnings-are-not-exceptions).

> [!NOTE]
>
> The 3.9.0 changelog includes the entry "runtime: remove beta label from v2 endpoints". However, version 3.10.0 still emits `BetaWarning` for the `client.runtime` evaluation methods. The current beta status of these endpoints needs confirmation. Until it is confirmed, treat them as beta.

## Check your installed version

Print the version your code is actually using:

```python theme={null}
import hiddenlayer

print(hiddenlayer.__version__)
```

You can also ask pip:

**macOS/Linux**

```bash theme={null}
python -m pip show hiddenlayer-sdk
```

**Windows**

```powershell theme={null}
py -m pip show hiddenlayer-sdk
```

If the version is older than you expect after an upgrade, your code is probably running in a different Python environment than the one you upgraded. See [Troubleshooting](/docs/integrations/sdk_python/troubleshooting).

## Upgrade the SDK

Follow these steps to upgrade safely:

**1. Review the changelog**

Read the [CHANGELOG](https://github.com/hiddenlayerai/hiddenlayer-sdk-python/blob/main/CHANGELOG.md) for every version between your current version and the target version. Look for deprecations, behavior changes, and changes to beta APIs you use.

**2. Upgrade in a test environment first**

Create or activate a separate virtual environment, then upgrade:

**macOS/Linux**

```bash theme={null}
python -m pip install --upgrade hiddenlayer-sdk
```

**Windows**

```powershell theme={null}
py -m pip install --upgrade hiddenlayer-sdk
```

To install a specific version, use `python -m pip install hiddenlayer-sdk==3.10.0`.

**3. Run your tests**

Run your test suite and type checker. Watch for new `DeprecationWarning` or `BetaWarning` messages, which point to code that you should update.

**4. Pin the version**

Pin the version in your `requirements.txt` or `pyproject.toml` so every environment installs the same version. Use an exact pin when you rely on beta APIs:

```text theme={null}
hiddenlayer-sdk==3.10.0
```

If you use only GA APIs, you can allow compatible minor and patch releases:

```text theme={null}
hiddenlayer-sdk>=3.10,<4
```

## Upgrade notes

### Deprecated top-level fields on `ScanReport`

These top-level `ScanReport` fields are deprecated. Read the same values from `report.summary` instead:

| Deprecated | Use instead |
| - | - |
| `report.detection_count` | `report.summary.detection_count` |
| `report.file_count` | `report.summary.file_count` |
| `report.files_with_detections_count` | `report.summary.files_with_detections_count` |
| `report.detection_categories` | `report.summary.detection_categories` |
| `report.severity` | `report.summary.highest_severity` |

`report.summary.severity` is also deprecated. Use `report.summary.highest_severity`. Some older examples, including `examples/demo.py` in the SDK repository, still use the deprecated top-level fields.

```python theme={null}
import sys

import hiddenlayer
from hiddenlayer import HiddenLayer

with HiddenLayer() as client:
    try:
        report = client.model_scanner.scan_file(model_name="my-model", model_path=sys.argv[1])
    except hiddenlayer.APIError as e:
        sys.exit(f"Scan failed: {e}")

print("Status:", report.status)
print("Detections:", report.summary.detection_count)
print("Highest severity:", report.summary.highest_severity)
```

### Scan report assembly changed in 3.10.0

Starting in 3.10.0, the model scanning helpers (`scan_file`, `scan_folder`, `scan_s3_model`, `scan_azure_blob_model`, `scan_huggingface_model`, `community_scan`, and `scan_result`) build the `ScanReport` differently. They poll the scan summary endpoint until the scan finishes, then read file results page by page. The return type is still `ScanReport`.

If you call the helpers with `wait_for_results=False` while a scan is still running, the report is a point-in-time snapshot. File results can be incomplete, so check `report.status` before you rely on them. See [Model scanning](/docs/integrations/sdk_python/model_scanning).

### `client.models.cards.list` is deprecated

`client.models.cards.list()` is deprecated in favor of the `GET /asset-inventory/v2/assets` API endpoint. The method still works in 3.10.0, but avoid using it in new code.

> [!NOTE]
>
> The 3.9.0 changelog mentions exposing the v2 AI Asset Inventory API, but version 3.10.0 of the SDK does not include a client method for it. When a replacement method will be available needs confirmation.

### Sensor endpoints are deprecated

The `client.sensors` methods (`create`, `retrieve`, `update`, `delete`, and `query`) are deprecated. Their documentation states that the endpoints will be removed after April 13, 2026. Do not use them in new code.

### `start_session` defaults changed in 3.8.0

In 3.8.0, `client.evaluation_sessions.red_team.start_session` stopped applying hard-coded defaults and now forwards all parameters to the API. If you upgrade from an earlier version and relied on the old defaults, review the arguments you pass. See [AI Attack Simulation](/docs/integrations/sdk_python/attack_simulation).

### Upgrading from alpha versions

If you use a `0.1.0-alpha.*` version, upgrade to the latest 3.x release. The alpha releases included frequent API updates.

> [!NOTE]
>
> No migration guide from the alpha versions to 3.x is available. Whether specific breaking changes apply needs confirmation. Review the [CHANGELOG](https://github.com/hiddenlayerai/hiddenlayer-sdk-python/blob/main/CHANGELOG.md) and test your code before upgrading.

### Upgrading from the legacy HiddenLayer SDK

The current SDK replaces an earlier HiddenLayer Python SDK. To ease the transition, the `client.model_scanner` and `client.community_scanner` helpers provide the same scanning functionality as the legacy SDK's `ModelScanAPI` and `community_scan`. Method names, parameters, and return types may still differ.

> [!NOTE]
>
> No migration guide from the legacy SDK is available. Exact differences between the legacy SDK and the current helpers need confirmation. Test your scanning code against the current SDK before switching.

## Next steps

* [Installation](/docs/integrations/sdk_python/installation): install or reinstall the SDK.
* [Security and production guidance](/docs/integrations/sdk_python/security): pin versions and configure the client for production.
* [Python API reference](/docs/integrations/sdk_python/api_reference): see every resource and method.