Skip to content

Installation

alpha-visualizer is published on PyPI and requires Python 3.12+.

You can try it without AlphaForge

alpha-visualizer ships with synthetic sample data, so you can explore every screen without installing AlphaForge (see Try it right after installing below). Once you want to visualize your own backtest results, install alpha-forge — the engine that produces backtest_results.db — via the AlphaForge Getting Started guide (latest binaries are also on GitHub Releases).

Requirements

Item Version
Python 3.12 or later
OS macOS / Linux / Windows
Browser Latest Chrome / Firefox / Safari / Edge

uv installs the tool into an isolated environment, sidestepping Python version conflicts.

uv tool install alpha-visualizer

If you don't have uv yet, see https://docs.astral.sh/uv/getting-started/installation/.

pip

Plain Python installation:

pip install alpha-visualizer

Inside a virtualenv:

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install alpha-visualizer

From source (for development)

Clone the repo and run locally:

git clone https://github.com/alforge-labs/alpha-visualizer.git
cd alpha-visualizer
uv sync                            # Python deps
cd frontend && pnpm install && pnpm run build && cd ..
uv run alpha-vis serve --forge-dir <path>

See CONTRIBUTING.en.md for the full development workflow.

Verify the install

alpha-vis --version

A correctly installed alpha-vis prints its version.

Try it right after installing (sample data)

You can run the whole dashboard on bundled synthetic sample data — no AlphaForge install and no backtest results of your own required.

alpha-vis serve --use-bundled-samples

Your browser opens automatically (or visit http://127.0.0.1:8000) with sample strategies, backtest results, and ideas, letting you walk through Browse / Detail / Compare and the other screens. With --use-bundled-samples, the --forge-dir / --forge-config options are ignored.

When you are ready to look at your own data, run a backtest with alpha-forge and start the server like this:

alpha-vis serve --forge-dir /path/to/your/alpha-strategies

Upgrade

# uv
uv tool upgrade alpha-visualizer

# pip
pip install --upgrade alpha-visualizer

Uninstall

# uv
uv tool uninstall alpha-visualizer

# pip
pip uninstall alpha-visualizer

Next steps