Install Bengal

Install Bengal using pip, uv, or from source

3 min read 501 words
Edit this page

Was this page helpful?

Install Bengal on your machine before scaffolding a site or contributing to the project.

Note

Do I need this? Yes ifbengal --versionfails or you are setting up a new machine. Skip if Bengal is already installed and up to date.

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

BASH
uv add bengal

Or for a one-time run:

BASH
uvx bengal --version
BASH
pip install bengal

Verify installation:

BASH
bengal --version
BASH
pipx install bengal

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

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

BASH
git clone https://github.com/your-org/bengal.git
cd bengal
pip install -e .

This installs Bengal in development mode, allowing you to modify the source code.

This installs Bengal in editable mode with development dependencies.

Verify Installation

BASH
bengal --version

You should see output like: bengal 0.5.1(version matches your installed release).

Upgrade Bengal

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

BASH
# 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:

BASH
# 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.

BASH
# 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:

BASH
source .venv/bin/activate

Try reinstalling:

BASH
pip uninstall bengal && pip install bengal
Python version errors

Verify your Python version:

BASH
python --version
# or
python3 --version

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

Permission errors

Use the--userflag:

BASH
pip install --user bengal

Or use a virtual environment:

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

Next Steps