Skip to main content
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

​
Install from PyPI

The recommended way to install the HopX Python SDK: 
pip install hopx-ai

​
Install Specific Version

Install a specific version: 
pip install hopx-ai==0.3.0

​
Install from Source

For development or to use the latest unreleased version: 
git clone https://github.com/hopx-ai/hopx.git
cd HopX/python
pip install -e .

​
Verify Installation

Verify the installation: 
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: Set the HOPX_API_KEY environment variable: 
# 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: 
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: 
# .env
HOPX_API_KEY=your-API key-here
Then load it in your Python code: 
from dotenv import load_dotenv
import os
from hopx_ai import Sandbox

load_dotenv()
sandbox = Sandbox.create(template="code-interpreter")
Never commit your API key to version control. Always use environment variables or secure secret management for production applications.

​
Get Your API key

  1. Sign up at 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)
API keys are scoped to your account and have full access to create, manage, and delete sandboxes. Keep them secure.

​
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

pip install hopx-ai

​
poetry

poetry add hopx-ai

​
pipenv

pipenv install hopx-ai

​
conda

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

​
Next Steps

Once you’ve successfully installed the SDK: