Skip to content

Installation

This guide covers all installation methods for QubitOS.

Requirements

Component Minimum Version Recommended
Python 3.11 3.12
Rust 1.83 Latest stable
pip 23.0 Latest

Quick Install (Python Package Only)

If you only need the Python client and pulse generation:

pip install qubitos

Verify the installation:

python -c "import qubitos; print(f'QubitOS {qubitos.__version__}')"

Full Installation (Client + HAL Server)

For the complete QubitOS experience, you need both the Python package and the HAL server.

Step 1: Install Python Package

pip install qubitos

git clone https://github.com/qubit-os/qubit-os-core.git
cd qubit-os-core
pip install -e ".[dev]"

pip install "qubitos[dev]"

Step 2: Install HAL Server

The HAL server is written in Rust and provides the quantum backend interface.

# Clone the repository
git clone https://github.com/qubit-os/qubit-os-hardware.git
cd qubit-os-hardware

# Build in release mode
cargo build --release

# The binary will be at target/release/qubit-os-hal

# Pull the image
docker pull ghcr.io/qubit-os/qubit-os-hardware:latest

# Run the server
docker run -p 50051:50051 -p 8080:8080 \
    ghcr.io/qubit-os/qubit-os-hardware:latest

Pre-built binaries will be available in future releases. For now, build from source.

Step 3: Verify Installation

# Start the HAL server (in one terminal)
cd qubit-os-hardware
cargo run --release

# In another terminal, test the connection
qubit-os hal health --server localhost:50051

Expected output:

HAL Server Health Check
───────────────────────
Status: healthy
Backends:
  • qutip_simulator: healthy (Simulator)

Platform-Specific Instructions

Linux (Ubuntu/Debian)

# Install system dependencies
sudo apt update
sudo apt install -y python3.11 python3.11-venv python3-pip

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# Install QubitOS
pip install qubitos

macOS

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Python and Rust
brew install python@3.12 rust

# Install QubitOS
pip install qubitos

QubitOS is best used on Windows through WSL2:

# Install WSL2 with Ubuntu
wsl --install -d Ubuntu

# Then follow the Linux instructions inside WSL

Development Installation

For contributing to QubitOS:

# Clone all repositories
git clone https://github.com/qubit-os/qubit-os-proto.git
git clone https://github.com/qubit-os/qubit-os-hardware.git
git clone https://github.com/qubit-os/qubit-os-core.git

# Set up Python environment
cd qubit-os-core
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,docs]"

# Install pre-commit hooks
pre-commit install

# Run tests
pytest tests/

Environment Variables

QubitOS can be configured through environment variables:

Variable Description Default
QUBITOS_HAL_SERVER HAL server address localhost:50051
QUBITOS_LOG_LEVEL Logging level INFO
QUBITOS_CONFIG_PATH Config file path ~/.config/qubitos/config.yaml
QUBITOS_STRICT_VALIDATION Enable strict validation false

Example:

export QUBITOS_HAL_SERVER="192.168.1.100:50051"
export QUBITOS_LOG_LEVEL="DEBUG"

Virtual Environment Best Practices

We recommend using virtual environments:

# Create a virtual environment
python -m venv qubitos-env

# Activate it
source qubitos-env/bin/activate  # Linux/macOS
# or
qubitos-env\Scripts\activate     # Windows

# Install QubitOS
pip install qubitos

# Deactivate when done
deactivate

Troubleshooting Installation

Common Issues

ModuleNotFoundError: No module named 'qubitos'

Ensure you've activated your virtual environment:

source .venv/bin/activate

grpcio installation fails

You may need to install build dependencies:

# Ubuntu/Debian
sudo apt install python3-dev build-essential

# macOS
xcode-select --install

Rust compilation errors

Ensure you have Rust 1.83+:

rustup update
rustc --version  # Should be >= 1.83

For more troubleshooting, see the Troubleshooting Guide.

Next Steps