Installation - HiddenLayer Docs

This page shows you how to install the hiddenlayer-sdk package from PyPI into a virtual environment, add optional packages, and confirm that the installation works. Before you start, check the Prerequisites.

Create a virtual environment

A virtual environment is an isolated Python installation for one project. Use one because:

The SDK’s dependencies, such as httpx and pydantic, do not conflict with other projects.
You can pin exact versions per project and reproduce them on other machines.
You do not need administrator rights to install packages.

Create and activate a virtual environment in your project folder:

macOS/Linux
Windows

mkdir hiddenlayer-project
cd hiddenlayer-project
python3 -m venv .venv
source .venv/bin/activate

mkdir hiddenlayer-project
cd hiddenlayer-project
py -m venv .venv
.venv\Scripts\Activate.ps1

If PowerShell blocks the activation script with an execution policy error, allow local scripts for your user and try again:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

When the environment is active, your shell prompt usually starts with (.venv). Inside an active environment, python and pip refer to the environment’s interpreter on every operating system.

Activate the environment in every new terminal session before you run your code. To leave the environment, run deactivate.

Upgrade pip

Older pip versions can fail to resolve recent packages. Upgrade pip inside the environment:

python -m pip install --upgrade pip

Install the SDK

Install the package:

python -m pip install hiddenlayer-sdk

The PyPI package name is hiddenlayer-sdk, but you import it in Python as hiddenlayer.

Running python -m pip instead of pip guarantees that the package is installed for the same interpreter that runs your code.

Install optional packages

Install these only if you use the related feature.

aiohttp backend for the async client

By default, the async client uses httpx. For better concurrency, you can use aiohttp as the HTTP backend. Install the aiohttp extra:

python -m pip install "hiddenlayer-sdk[aiohttp]"

Keep the quotes. Some shells, such as zsh (the default on macOS), treat square brackets as a filename pattern and fail with no matches found. To use the backend, pass http_client=DefaultAioHttpClient() to AsyncHiddenLayer. See Authentication and configuration.

Cloud and Hugging Face model scanning helpers

Some model scanning helpers download models with third-party libraries. These are not SDK extras, so install them separately:

Helper	Install command
`client.model_scanner.scan_huggingface_model`	`python -m pip install huggingface_hub`
`client.model_scanner.scan_s3_model`	`python -m pip install boto3`
`client.model_scanner.scan_azure_blob_model`	`python -m pip install azure-identity azure-storage-blob`

If a package is missing when you call the helper, the SDK raises an ImportError, for example Python package boto3 is not installed.

Loading credentials from a .env file

The SDK reads environment variables but does not load .env files itself. To load them from a file during local development, install python-dotenv:

python -m pip install python-dotenv

See Authentication and configuration for usage.

Verify the installation

Print the installed SDK version:

python -c "import hiddenlayer; print(hiddenlayer.__version__)"

The output is a version number, for example:

3.11.0

You can also check package details with pip:

python -m pip show hiddenlayer-sdk

Installation does not contact HiddenLayer or check your credentials. To confirm that you can reach the API, complete the Quickstart.

Pin versions

Pin the SDK version so that every developer and every deployment uses the same code. Add a line to your requirements.txt file:

requirements.txt

hiddenlayer-sdk==3.11.0

Or allow compatible minor and patch updates within the same major version:

requirements.txt

hiddenlayer-sdk>=3.11,<4

Install from the file:

python -m pip install -r requirements.txt

The SDK generally follows semantic versioning, but some backwards-incompatible changes can ship in minor releases, and beta APIs are excluded from versioning guarantees. An exact pin is the safest choice for production. See Version compatibility and upgrades.

Upgrade or uninstall

Upgrade to the latest release:

python -m pip install --upgrade hiddenlayer-sdk

Uninstall the SDK:

python -m pip uninstall hiddenlayer-sdk

Before upgrading, review the changelog in the GitHub repository for changes that affect your code.

Common installation errors

ModuleNotFoundError: No module named 'hiddenlayer'

Python cannot find the SDK in the interpreter that runs your code. Usually this means the virtual environment is not active, or the SDK was installed into a different environment.To fix it:

Activate the project’s virtual environment (see Create a virtual environment).
Run python -m pip show hiddenlayer-sdk. If nothing is shown, install the SDK again with python -m pip install hiddenlayer-sdk.
In an IDE such as VS Code or PyCharm, select the .venv interpreter for the project.

Also confirm that you import hiddenlayer, not hiddenlayer_sdk.

pip installs the package, but Python still cannot import it

On machines with several Python installations, the pip command can belong to a different interpreter than python. Always install with python -m pip ... so that pip runs under the same interpreter as your code.To see which interpreter you are using, run:

python -c "import sys; print(sys.executable)"

The path should point inside your .venv folder.

zsh: no matches found: hiddenlayer-sdk[aiohttp]

zsh interprets the square brackets as a filename pattern. Put the package specifier in quotes:

python -m pip install "hiddenlayer-sdk[aiohttp]"

ERROR: Could not find a version that satisfies the requirement hiddenlayer-sdk

Your Python version may be older than 3.9, or pip cannot reach PyPI. Check python --version, upgrade pip, and confirm that your network or package mirror allows access to PyPI.

For other problems, see Troubleshooting.

Next step

Authentication and configuration

Provide your client ID and client secret, and choose your region.

​Create a virtual environment

​Upgrade pip

​Install the SDK

​Install optional packages

​aiohttp backend for the async client

​Cloud and Hugging Face model scanning helpers

​Loading credentials from a .env file

​Verify the installation

​Pin versions

​Upgrade or uninstall

​Common installation errors

​Next step

Authentication and configuration

Create a virtual environment

Upgrade pip

Install the SDK

Install optional packages

aiohttp backend for the async client

Cloud and Hugging Face model scanning helpers

Loading credentials from a .env file

Verify the installation

Pin versions

Upgrade or uninstall

Common installation errors

Next step