# Performance

URL: /bengal/docs/ship/performance/
Section: performance
Description: Optimize Bengal build performance

---

> For a complete page index, fetch /bengal/llms.txt.

Speed up Bengal with incremental builds, parallel processing, and smart caching.

Note

Do I need this? Skip if your site builds in under 10 seconds. Read when you
have 500+ pages, slow CI, or template edits that rebuild too much.

Large Site Optimization

Build and render 5K-100K+ pages efficiently with streaming, parallel processing, and query indexes

(/bengal/docs/ship/performance/large-sites/)

Template Dependency Tracking

Selective rebuilds when templates change — only affected pages rebuild

(/bengal/docs/ship/performance/template-deps/)

## Quick Wins

Bengal optimizes builds automatically — no configuration required:

- Parallel processing: Auto-enabled based on page count and CPU cores

- Incremental builds: Auto-enabled when build cache exists

- Smart caching: Tracks file changes, dependencies, and parsed content

- Template dependency tracking: Records per-page template chains; template edits rebuild only affected pages

- Fast mode: Skips HTML formatting for faster builds (`--fast` or `build.fast_mode`)

- Render-time asset tracking: Tracks assets during template rendering (no HTML parsing)

- Autodoc AST caching: Caches parsed Python modules to skip AST parsing on subsequent builds

toml
TOML

```
# bengal.toml — only needed to override defaults
[build]
max_workers = 8      # Limit parallel workers (default: auto-detect)
```
## How Builds Get Faster

flowchart LR
A[Change file.md] --> B{Changed?}
B -->|Yes| C[Rebuild page]
B -->|No| D[Skip]
C --> E[Cache result]
D --> F[Use cached]
E --> G[Output]
F --> G

## Performance Strategies

Strategy
Effort
Speedup
Best For

Incremental
Zero
15-50x
Development

Parallel
Zero
2-8x
Large sites, multi-core

Template Deps
Zero
5-20x
Template edits (selective rebuild)

Fast Mode
Zero
10-15%
CI/CD (skips HTML formatting)

Asset Tracking
Zero
20-25%
Sites with many assets

Autodoc Caching
Zero
30-40%
Sites with autodoc (caches AST parsing)

Memory Optimized
Zero
N/A
5K+ pages

Note

Parallel speedup depends on Python version: 2-3x with standard Python, 6-8x with free-threaded Python 3.14+.

## Common Commands

BASH

```
# Fast mode: quiet output, auto-parallel
bengal build --fast

# Force full rebuild (skip cache)
bengal build --no-incremental

# Clear build cache
bengal clean --cache

# Profile build time (saves to .bengal/profiles/)
bengal build --perf-profile

# Profile template rendering
bengal build --profile-templates
```

Tip

Development workflow: Keep`bengal serve`running — it uses all optimizations automatically. Full builds are only needed for production.

## In This Section

Large Site Optimization (/bengal/docs/ship/performance/large-sites/)

Build and render 5K-100K+ pages efficiently with streaming, parallel processing, and query indexes

Template Dependency Tracking (/bengal/docs/ship/performance/template-deps/)

Selective rebuilds when templates change — only affected pages rebuild

Related Pages

Configuration (/bengal/docs/ship/configuration/)

Configuring Bengal with bengal.toml

Related

Internationalization (i18n) (/bengal/docs/build-sites/structure/i18n/)

Multi-language sites with gettext PO/MO, RTL support, and translation workflows

Related

Ship (/bengal/docs/ship/)

Build configuration, SEO/discovery, output formats, and deployment

Related

Analysis (/bengal/docs/build-sites/structure/analysis/)

Site structure analysis tools

Related

Versioned Documentation (/bengal/docs/build-sites/structure/versioning/)

Serve multiple versions of your documentation from a single site

Related

persona-operator (/bengal/tags/persona-operator/)