Version compatibility and upgrades

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.

Versioning policy

The SDK generally follows Semantic Versioning (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:

Changes that only affect static types, without breaking runtime behavior.
Changes to library internals that are technically public but not intended or documented for external use.
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 on the developer portal. To handle the warning in code, see Error handling.

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:

import hiddenlayer

print(hiddenlayer.__version__)

You can also ask pip:

macOS/Linux
Windows

python -m pip show hiddenlayer-sdk

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.

Upgrade the SDK

Follow these steps to upgrade safely:

Review the changelog

Read the CHANGELOG for every version between your current version and the target version. Look for deprecations, behavior changes, and changes to beta APIs you use.

Upgrade in a test environment first

Create or activate a separate virtual environment, then upgrade:

macOS/Linux
Windows

python -m pip install --upgrade hiddenlayer-sdk

py -m pip install --upgrade hiddenlayer-sdk

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

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.

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:

hiddenlayer-sdk==3.10.0

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

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.

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.

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

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.

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.

No migration guide from the alpha versions to 3.x is available. Whether specific breaking changes apply needs confirmation. Review the CHANGELOG 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.

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: install or reinstall the SDK.
Security and production guidance: pin versions and configure the client for production.
Python API reference: see every resource and method.

​Supported Python versions

​Dependencies

​Versioning policy

​Beta APIs

​Check your installed version

​Upgrade the SDK

​Upgrade notes

​Deprecated top-level fields on ScanReport

​Scan report assembly changed in 3.10.0

​client.models.cards.list is deprecated

​Sensor endpoints are deprecated

​start_session defaults changed in 3.8.0

​Upgrading from alpha versions

​Upgrading from the legacy HiddenLayer SDK

​Next steps

Supported Python versions

Dependencies

Versioning policy

Beta APIs

Check your installed version

Upgrade the SDK

Upgrade notes

Deprecated top-level fields on `ScanReport`

Scan report assembly changed in 3.10.0

`client.models.cards.list` is deprecated

Sensor endpoints are deprecated

`start_session` defaults changed in 3.8.0

Upgrading from alpha versions

Upgrading from the legacy HiddenLayer SDK

Next steps