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

# Installation

> Install the HiddenLayer Python SDK in a virtual environment, add optional packages, and verify the installation.

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](/docs/integrations/sdk_python/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**

```bash theme={null}
mkdir hiddenlayer-project
cd hiddenlayer-project
python3 -m venv .venv
source .venv/bin/activate
```

**Windows**

```powershell theme={null}
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:

```powershell theme={null}
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.

> [!NOTE]
>
> 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:

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

## Install the SDK

Install the package:

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

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

> [!TIP]
>
> 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:

```bash theme={null}
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](/docs/integrations/sdk_python/authentication#async-client).

### 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`:

```bash theme={null}
python -m pip install python-dotenv
```

See [Authentication and configuration](/docs/integrations/sdk_python/authentication#optional-use-a-env-file) for usage.

## Verify the installation

Print the installed SDK version:

```bash theme={null}
python -c "import hiddenlayer; print(hiddenlayer.__version__)"
```

The output is a version number, for example:

```text theme={null}
3.11.0
```

You can also check package details with `pip`:

```bash theme={null}
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](/docs/integrations/sdk_python/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:

```text requirements.txt theme={null}
hiddenlayer-sdk==3.11.0
```

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

```text requirements.txt theme={null}
hiddenlayer-sdk>=3.11,<4
```

Install from the file:

```bash theme={null}
python -m pip install -r requirements.txt
```

> [!NOTE]
>
> 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](/docs/integrations/sdk_python/versioning).

## Upgrade or uninstall

Upgrade to the latest release:

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

Uninstall the SDK:

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

Before upgrading, review the changelog in the [GitHub repository](https://github.com/hiddenlayerai/hiddenlayer-sdk-python) 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:
>
> 1. Activate the project's virtual environment (see [Create a virtual environment](#create-a-virtual-environment)).
> 2. Run `python -m pip show hiddenlayer-sdk`. If nothing is shown, install the SDK again with `python -m pip install hiddenlayer-sdk`.
> 3. 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:
>
> ```bash theme={null}
> 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:
>
> ```bash theme={null}
> 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](/docs/integrations/sdk_python/troubleshooting).

## Next step

> **[Authentication and configuration](/docs/integrations/sdk_python/authentication)**
>
> Provide your client ID and client secret, and choose your region.