Skip to content

installation.md

Latest commit

 

History

History
147 lines (104 loc) · 5.88 KB

installation.md

File metadata and controls

147 lines (104 loc) · 5.88 KB
Raw

Installation and environment setup

BenchBox requires Python 3.11 or newer and ships as a single Python package. The recommended workflow uses uv for fast installs, but the commands below include alternatives for pip and pipx.

BenchBox plans to require Python 3.12 in its first release after Python 3.11 reaches end of life in October 2027.

1. Install BenchBox

# Recommended: uv (modern package management)
uv add benchbox

# Alternative (pip-compatible)
uv pip install benchbox

# Traditional pip (uses the active Python environment)
python -m pip install benchbox

# pipx for a dedicated CLI environment
pipx install benchbox

BenchBox installs a benchbox executable. If you use uv, prefer uv run -- benchbox <command> to ensure the project virtual environment is activated automatically.

(installation-extras)=

2. Pick Optional Extras

Extras keep the base install lean.

Choose the smallest extra that supports the platform you plan to run. This keeps installation faster, reduces dependency conflicts, and avoids installing cloud SDKs or database drivers that you do not use. You can add another extra later by running the matching install command again.

Extra Enables Recommended (uv) Alternative (pip-compatible)
(none) SQLite only (core package, no DuckDB) uv add benchbox uv pip install benchbox
[duckdb] DuckDB for local analytics uv add benchbox --extra duckdb uv pip install "benchbox[duckdb]"
[cloudstorage] Cloud path helpers (S3, GCS, Azure) uv add benchbox --extra cloudstorage uv pip install "benchbox[cloudstorage]"
[cloud] Databricks, BigQuery, Redshift, Snowflake connectors uv add benchbox --extra cloud uv pip install "benchbox[cloud]"
[clickhouse] ClickHouse native driver uv add benchbox --extra clickhouse uv pip install "benchbox[clickhouse]"
[databricks] / [bigquery] / [redshift] / [snowflake] Single-platform installs uv add benchbox --extra databricks uv pip install "benchbox[databricks]"
[all] Everything listed above uv add benchbox --extra all uv pip install "benchbox[all]"

DuckDB 2.0 Preview

Stable DuckDB releases remain the default. To test the current DuckDB 2.0 preview, install BenchBox's DuckDB extra and then select the preview package explicitly:

# uv project
uv add benchbox --extra duckdb
uv add --prerelease=allow "duckdb==1.6.0.dev379"

# Active pip environment
python -m pip install "benchbox[duckdb]" "duckdb==1.6.0.dev379"

DuckDB distributes the 2.0 alpha engine in the Python package's 1.6 development series. BenchBox's nightly checks pin 1.6.0.dev379, which contains engine v2.0.0-alpha39998, so a later preview does not enter supported environments without a compatibility run and an explicit pin update.

Cloud Spark Platforms

For managed Spark platforms, use provider-specific extras to install only the dependencies you need:

Extra Platforms Dependencies
[cloud-spark-aws] AWS Glue, EMR Serverless, Athena Spark boto3
[cloud-spark-gcp] Google Cloud Dataproc, Dataproc Serverless google-cloud-dataproc, google-cloud-storage
[cloud-spark-azure] Azure Synapse Analytics Spark, Fabric Spark azure-identity, azure-storage-file-datalake, requests
[cloud-spark-snowflake] Snowflake Snowpark snowflake-snowpark-python, pyspark
[cloud-spark-databricks] Databricks Connect databricks-connect, databricks-sdk
[cloud-spark] All cloud Spark platforms All of the above 
# AWS users: Install only AWS Spark dependencies
uv add benchbox --extra cloud-spark-aws

# Multi-cloud: Install all cloud Spark dependencies
uv add benchbox --extra cloud-spark

# Combine with other extras
uv add benchbox --extra cloud-spark-aws --extra athena

Combining Extras

# Recommended: Enable all cloud platforms and ClickHouse
uv add benchbox --extra cloud --extra clickhouse

# Alternative (pip-compatible)
uv pip install "benchbox[cloud,clickhouse]"

Re-run the installer at any time to add extras. For pipx, use pipx inject benchbox "benchbox[cloud]".

Choose an installer

  • Use uv add when BenchBox is a dependency of a Python project.
  • Use python -m pip install in an activated virtual environment when your project uses pip.
  • Use pipx install when you want an isolated, system-wide benchbox command.
  • Quote "benchbox[extra]" with pip-compatible commands so shells such as zsh do not interpret the brackets.

3. Verify the CLI

uv run -- benchbox --version

The command prints the current BenchBox version and validates that pyproject.toml, benchbox/__init__.py, and doc version markers match.

4. Run Dependency Checks

benchbox check-deps inspects optional connectors and suggests install commands.

# Overview of all platforms
uv run -- benchbox check-deps

# Detailed matrix with extras guidance
uv run -- benchbox check-deps --matrix

# Focus on a single platform
uv run -- benchbox check-deps --platform snowflake --verbose

5. Create a Workspace (Optional)

BenchBox stores generated data and results under benchmark_runs/ by default. Set a custom location with --output PATH when invoking benchbox run, or point to cloud storage such as s3:// or gs:// if the corresponding extras are installed.

For repeatable environments, initialise a project-level virtual environment with uv venv .venv && source .venv/bin/activate (or the Windows equivalent) before running the commands above.

Next Steps