Install Bengal

Install Bengal using pip, uv, or from source

2 min read 482 words

Requirements

Bengal requires Python 3.14 or later. For best performance, use the free-threaded build (Python 3.14t), which enables true parallel processing.

Install

uv pip install bengal

Or for a one-time run without installation:

uvx bengal --version

pip install bengal

pipx install bengal

This installs Bengal in an isolated environment while making the bengalcommand available globally.

git clone https://github.com/lbliii/bengal.git
cd bengal
make setup
make install

This installs Bengal in editable mode with development dependencies.

Verify Installation

bengal --version

You should see output like: Bengal SSG, version 0.1.10

Upgrade Bengal

Bengal includes a built-in upgrade command that automatically detects how it was installed:

# Interactive upgrade (recommended)
bengal upgrade

# Skip confirmation
bengal upgrade -y

# Preview changes without executing
bengal upgrade --dry-run

The upgrade command:

  • Detects your installer (uv, pip, pipx, conda)
  • Checks PyPI for the latest version (cached for 24 hours)
  • Shows a confirmation before making changes

Tip

Bengal will show a notification after commands when a new version is available. You can disable this by settingBENGAL_NO_UPDATE_CHECK=1in your environment.

Python Version Setup

pyenv lets you install and switch between multiple Python versions:

# macOS (with Homebrew)
brew install pyenv

# Install Python 3.14
pyenv install 3.14.0

# Set as default
pyenv global 3.14.0

# Verify
python --version

Download Python 3.14 from python.org/downloads.

After installation, verify:python3 --version

Free-Threaded Python

For best build performance, use the free-threaded Python build (Python 3.14t). This enables true parallel processing for 1.5-2x faster builds on multi-core machines.

# With pyenv
pyenv install 3.14.0t
pyenv global 3.14.0t

# Verify free-threading is enabled
python -c "import sys; print('Free-threaded!' if sys._is_gil_enabled() == False else 'GIL enabled')"

Bengal automatically detects the free-threaded build and enables parallel processing.

Troubleshooting

Command not found

Ensure Python's bin directory is in your PATH.

If using a virtual environment, activate it:

source .venv/bin/activate

Try reinstalling:

pip uninstall bengal && pip install bengal
Python version errors

Verify your Python version:

python --version
# or
python3 --version

Bengal requires Python 3.14 or later. Install using pyenv or the official installer.

Permission errors

Use the--userflag:

pip install --user bengal

Or use a virtual environment:

python -m venv venv && source venv/bin/activate
pip install bengal

Next Steps