Installation

quickstart installation setup

Installation

This guide covers installing the Huitzo SDK and CLI tools for pack development.

Prerequisites

  • Python 3.11+ – The SDK requires Python 3.11 or later (3.14 recommended)
  • uv (recommended) or pip – Package manager
  • Internet connection – Pack development uses Huitzo's cloud sandbox
  • Huitzo account – Sign up at huitzo.com

Platform Support

Platform Supported Notes
Linux (x86_64) ✅ Primary development platform
Linux (arm64) ✅ Native ARM support
macOS (Intel) ✅ Full support
macOS (Apple Silicon) ✅ Native ARM support
Windows 10/11 ✅ Native or WSL2

Install the SDK

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create a new project
uv init my-pack
cd my-pack

# Add the SDK
uv add huitzo-sdk

Using pip

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the SDK
pip install huitzo-sdk

Install the CLI

The Huitzo CLI is included with the SDK:

# Verify installation
huitzo --version
# Output: huitzo 0.0.0

CLI Commands

huitzo --help

# Core commands:
#   pack new      Create a new pack from template
#   pack dev      Start development session (cloud sandbox)
#   pack test     Run pack tests
#   pack build    Build pack for distribution
#   pack publish  Publish pack to registry
#   pack validate Validate pack manifest

Verify Installation

Create a simple test file:

# test_sdk.py
from huitzo_sdk import command, Context
from pydantic import BaseModel

class TestArgs(BaseModel):
    message: str

@command("test", namespace="demo")
async def test_command(args: TestArgs, ctx: Context) -> dict:
    return {"echo": args.message}

if __name__ == "__main__":
    print("SDK installed correctly!")

Run it:

python test_sdk.py
# Output: SDK installed correctly!

Development Environment Setup

Install these extensions for the best experience:

  • Python – Microsoft's Python extension
  • Pylance – Type checking and IntelliSense
  • Ruff – Fast linting and formatting
  • Even Better TOML – pyproject.toml support

Configure VS Code

Create .vscode/settings.json:

{
  "python.defaultInterpreterPath": ".venv/bin/python",
  "python.analysis.typeCheckingMode": "basic",
  "[python]": {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "charliermarsh.ruff"
  }
}

Authenticate with Huitzo

Before developing packs, log in to your Huitzo account:

huitzo login

This opens your browser for authentication. Once complete, you're ready to develop and test packs.

Note: Pack development uses Huitzo's cloud sandbox—you don't need to install PostgreSQL, Redis, or any other infrastructure locally. When you run huitzo pack dev, a local proxy starts on your machine that forwards requests to a cloud-hosted sandbox where your pack code executes.

See Developer Environment for more details on the development architecture.

Project Structure

Recommended project structure for a pack:

my-pack/
├── pyproject.toml          # Package configuration
├── README.md               # Pack documentation
├── .env                    # Local environment (gitignored)
├── .gitignore
├── src/
│   └── my_pack/
│       ├── __init__.py
│       ├── commands/       # Command implementations
│       │   ├── __init__.py
│       │   └── example.py
│       └── utils/          # Shared utilities
│           └── __init__.py
└── tests/
    ├── __init__.py
    └── test_example.py

Next Steps

Now that you have the SDK installed:

  1. Create Your First Pack – Build a working pack in 10 minutes
  2. SDK Overview – Understand the SDK architecture
  3. Commands Reference – Deep dive into command patterns

Windows Installation

Install Python 3.14 (or 3.11+):

# Using winget (Windows Package Manager)
winget install Python.Python.3.14

# Or using Scoop
scoop install python

Install uv:

# PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Create and activate project:

# Create project
uv init my-pack
cd my-pack

# Add SDK
uv add huitzo-sdk

# Activate virtual environment
.venv\Scripts\activate

# Verify installation
huitzo --version

If you need to run Docker containers or prefer a Linux environment:

# Install WSL2 (PowerShell as Admin)
wsl --install -d Ubuntu-24.04

Then follow the Linux installation instructions inside WSL2.

Windows Path Handling

The Huitzo SDK and CLI handle path differences automatically. However, keep in mind:

# Windows uses backslashes in paths
huitzo run mypack.command --file="C:\Users\me\data.csv"

# Forward slashes also work
huitzo run mypack.command --file="C:/Users/me/data.csv"

Windows-Specific Environment Variables

# Set environment variables in PowerShell
$env:HUITZO_API_URL = "http://localhost:8000"
$env:HUITZO_LOG_LEVEL = "DEBUG"

# Or permanently via System Properties
[System.Environment]::SetEnvironmentVariable("HUITZO_API_URL", "http://localhost:8000", "User")

Troubleshooting

"Module not found" errors

Make sure your virtual environment is activated:

# Linux/macOS
source .venv/bin/activate

# Windows PowerShell
.venv\Scripts\activate

# Windows Command Prompt
.venv\Scripts\activate.bat

"Python 3.11+ required"

Install Python 3.14 (or any version 3.11+):

# macOS with pyenv
pyenv install 3.14
pyenv local 3.14

# Ubuntu
sudo apt install python3.14 python3.14-venv
# Or for 3.11: sudo apt install python3.11 python3.11-venv

# Windows (PowerShell)
winget install Python.Python.3.14

Authentication errors

  1. Run huitzo logout then huitzo login to re-authenticate
  2. Check your internet connection
  3. Verify your Huitzo account is active

Sandbox connection errors

  1. Verify internet connectivity: curl -I https://huitzo.ai
  2. Check if you're behind a corporate proxy/firewall
  3. Run huitzo status to check connection

Getting Help