Installation

Install the Spice CLI and runtime on macOS, Linux, and Windows

Overview

Spice provides a command-line interface (CLI) and runtime that can be installed on macOS, Linux, and Windows.

The Spice CLI (spice) is used to initialize apps, manage datasets, and interact with the runtime. The Spice runtime (spiced) is the core engine that executes queries, manages data acceleration, and serves APIs.

Quick Install

macOS/Linux/WSL

curl https://install.spiceai.org | /bin/bash

Platform-Specific Installation

1. macOS and Linux

   Using the install script

   The recommended way to install Spice on macOS and Linux is using the install script:

   curl https://install.spiceai.org | /bin/bash
   

   This script will:

   • Download the latest release for your platform (macOS or Linux)
   • Install the spice CLI to $HOME/.spice/bin
   • Automatically add the Spice CLI to your PATH in your shell profile

   The installer supports bash, zsh, fish, ksh, and csh shells. It will detect your shell and update the appropriate profile file.

   Using Homebrew

   Alternatively, you can install Spice using Homebrew:

   brew install spiceai/spiceai/spice
   

   Manual PATH Configuration

   If the installer doesn’t automatically add Spice to your PATH, add the following to your shell profile:

   bash/zsh/ksh

   export PATH="$HOME/.spice/bin:$PATH"
   

   Then reload your shell:

   source ~/.bash_profile  # or ~/.zprofile, ~/.config/fish/config.fish, etc.
   
2. Windows

   Using PowerShell

   Install Spice on Windows using PowerShell:

   iex ((New-Object System.Net.WebClient).DownloadString("https://install.spiceai.org/Install.ps1"))
   

   This script will:

   • Download the latest Windows release (x86_64)
   • Install the spice.exe CLI to $HOME\.spice\bin
   • Automatically add the Spice CLI directory to your user PATH

   You may need to restart your terminal or PowerShell session for the PATH changes to take effect.

   Verifying the Installation

   After installation, verify that Spice is available:

   spice version
   

   If the command is not found, you may need to restart your terminal or manually add $HOME\.spice\bin to your PATH.

3. Supported Platforms

   Spice provides pre-built binaries for the following platforms:

   Platform	Architecture	Status
   Linux	x86_64	✅ Supported
   Linux	aarch64 (ARM64)	✅ Supported
   macOS	aarch64 (Apple Silicon)	✅ Supported
   Windows	x86_64	✅ Supported

   If your platform is not listed above, you may need to build Spice from source. See the GitHub repository for build instructions.

Docker Installation

Spice is available as a Docker image for containerized deployments:

Pull Image

docker pull spiceai/spiceai

The Docker image exposes:

• Port 8090: HTTP API
• Port 50051: Arrow Flight API
• Port 9090: Metrics

Kubernetes Installation

Deploy Spice to Kubernetes using Helm:

1. Add the Helm repository

   helm repo add spiceai https://helm.spiceai.org
   helm repo update
   
2. Install Spice

   helm install spiceai spiceai/spiceai
   

   Or with custom values:

   helm install spiceai spiceai/spiceai -f values.yaml
   
3. Verify the deployment

   kubectl get pods
   kubectl logs -l app=spiceai
   

Verifying Installation

After installation, verify that Spice is working correctly:

1. Check version

   spice version
   

   This should display the installed version of Spice.

2. Initialize a test app

   spice init test_app
   cd test_app
   
3. Run the runtime

   spice run
   

   You should see output indicating the runtime has started successfully:

   2025/01/20 11:26:10 INFO Spice.ai runtime starting...
   2025-01-20T19:26:10.679716Z  INFO runtime::flight: Spice Runtime Flight listening on 127.0.0.1:50051
   2025-01-20T19:26:10.680140Z  INFO runtime::http: Spice Runtime HTTP listening on 127.0.0.1:8090
   

Environment Variables

You can customize the installation using environment variables:

Variable	Description	Default
SPICE_CLI_INSTALL_DIR	Installation directory for the CLI	$HOME/.spice/bin
USE_SUDO	Use sudo for installation (Linux)	false
GITHUB_TOKEN	GitHub token for API access (optional)	None

Example: Custom Installation Directory

export SPICE_CLI_INSTALL_DIR="/usr/local/bin"
curl https://install.spiceai.org | /bin/bash

Upgrading Spice

To upgrade to the latest version of Spice, simply re-run the installation command:

macOS/Linux

curl https://install.spiceai.org | /bin/bash

Uninstalling Spice

To uninstall Spice:

1. Remove the binary

   rm -rf $HOME/.spice
   
2. Remove PATH configuration

   Edit your shell profile (e.g., ~/.bash_profile, ~/.zprofile) and remove the line that adds Spice to your PATH:

   export PATH="$HOME/.spice/bin:$PATH"
   
3. Reload your shell

   source ~/.bash_profile  # or your shell profile
   

Troubleshooting

Command not found after installation

If you see “command not found” after installation:

1. Restart your terminal or shell session
2. Verify the PATH was updated in your shell profile
3. Manually source your shell profile: source ~/.bash_profile (or appropriate file)
4. Check that the binary exists: ls -la $HOME/.spice/bin/spice

Permission denied errors

If you encounter permission errors during installation:

• Linux: The installer will automatically use sudo if needed
• macOS: Ensure you have write permissions to $HOME/.spice/bin
• Windows: Run PowerShell as Administrator

Download failures

If the download fails:

1. Check your internet connection
2. Verify you can access https://github.com
3. Try setting GITHUB_TOKEN if you’re hitting rate limits
4. Download the release manually from GitHub Releases

Next Steps

Quickstart

Get started with your first Spice app

Documentation

Read the full documentation

System Requirements

Learn about system requirements and supported platforms

GitHub

View the source code and contribute