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

# Installation

> Install the HopX Python SDK and set up your development environment. Get started with the official Python SDK for HopX, install via pip, configure API keys, and verify installation. Learn system requirements, installation methods, and troubleshooting tips. Includes installation examples for different Python versions and environments.

**SDK Version:** 0.3.0\
**Last Verified:** 2025-01-27

## Prerequisites

Before installing the HopX Python SDK, ensure you have:

* **Python 3.8+** (CPython recommended)
* **pip** (Python package installer)
* **HopX API key** - Get yours at [console.hopx.dev](https://console.hopx.dev)

## Install from PyPI

The recommended way to install the HopX Python SDK:

```bash theme={null}
pip install hopx-ai
```

## Install Specific Version

Install a specific version:

```bash theme={null}
pip install hopx-ai==0.3.0
```

## Install from Source

For development or to use the latest unreleased version:

```bash theme={null}
git clone https://github.com/hopx-ai/hopx.git
cd HopX/python
pip install -e .
```

## Verify Installation

Verify the installation:

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

Expected output: `0.3.0`

## Set Up Authentication

The SDK requires an API key for authentication. You have three options:

### Option 1: Environment Variable (Recommended)

Set the `HOPX_API_KEY` environment variable:

```bash theme={null}
# Linux/macOS
export HOPX_API_KEY="your-API key-here"

# Windows (PowerShell)
$env:HOPX_API_KEY="your-API key-here"

# Windows (CMD)
set HOPX_API_KEY=your-API key-here
```

### Option 2: Pass API key Directly

Pass the API key when creating a sandbox:

```python theme={null}
from hopx_ai import Sandbox

sandbox = Sandbox.create(
    template="code-interpreter",
    api_key="your-API key-here"
)
```

### Option 3: Configuration File

Create a `.env` file in your project root:

```bash theme={null}
# .env
HOPX_API_KEY=your-API key-here
```

Then load it in your Python code:

```python theme={null}
from dotenv import load_dotenv
import os
from hopx_ai import Sandbox

load_dotenv()
sandbox = Sandbox.create(template="code-interpreter")
```

<Warning>
  Never commit your API key to version control. Always use environment variables or secure secret management for production applications.
</Warning>

## Get Your API key

1. Sign up at [console.hopx.dev](https://console.hopx.dev)
2. Navigate to **Settings** → **API Keys**
3. Create a new API key
4. Copy the key (you'll only see it once)

<Note>
  API keys are scoped to your account and have full access to create, manage, and delete sandboxes. Keep them secure.
</Note>

## Supported Python Versions

The SDK is tested and supported on:

* **Python 3.8** - Minimum supported version
* **Python 3.9** - Recommended for best compatibility
* **Python 3.10** - Recommended for new projects
* **Python 3.11** - Recommended for new projects
* **Python 3.12** - Latest, fully supported

## Package Managers

### pip

```bash theme={null}
pip install hopx-ai
```

### poetry

```bash theme={null}
poetry add hopx-ai
```

### pipenv

```bash theme={null}
pipenv install hopx-ai
```

### conda

```bash theme={null}
conda install -c conda-forge hopx-ai
```

## Dependencies

The SDK has minimal dependencies:

* `requests` - HTTP client for API calls
* `websocket-client` - WebSocket support for streaming
* `typing-extensions` - Type hints for Python \< 3.10

All dependencies are automatically installed with `pip install hopx-ai`.

## Troubleshooting

### Import Errors

If you get `ModuleNotFoundError: No module named 'hopx_ai'`:

1. Verify Python version: `python --version` (should be 3.8+)
2. Check installation: `pip list | grep hopx-ai`
3. Reinstall: `pip install --upgrade hopx-ai`

### Authentication Errors

If you get authentication errors:

1. Verify API key is set: `echo $HOPX_API_KEY` (Linux/macOS) or `echo %HOPX_API_KEY%` (Windows)
2. Check API key is valid at [console.hopx.dev](https://console.hopx.dev)
3. Ensure no extra spaces or quotes in the API key

### Network Errors

If you encounter network errors:

1. Check internet connection
2. Verify firewall allows outbound HTTPS (port 443)
3. Check if you're behind a corporate proxy (may need proxy configuration)

For more troubleshooting help, see the [Troubleshooting Guide](/sdk/python/troubleshooting).

## Related

* **[Python SDK Quickstart](/sdk/python/quickstart)** - Get started with the SDK
* **\[API key Management]\(/API key)** - Learn about API key security
* **[Sandbox Class Reference](/sdk/python/sandbox)** - Complete SDK reference

## Next Steps

Once you've successfully installed the SDK:

* **[Quickstart Guide](/sdk/python/quickstart)** - Create your first sandbox and run code
* **[CLI Installation](/cli/installation)** - Install the HopX CLI as an alternative
* **[API Reference](/sdk/python/sandbox)** - Explore the full SDK API