Installation

QA Lens can be installed from PyPI, run in Docker, or installed from source for development.

Install From PyPI

pip install qalens

This installs:

• The qalens CLI.
• The FastAPI backend.
• The bundled React web UI.
• The report parsers and deterministic analyzers.

No Node.js is required for PyPI users.

Verify:

qalens --version
qalens --help

Run With Docker

Use Docker when you want an isolated installation with no local Python or Node.js setup.

Requirements:

• A running Docker engine, such as Docker Desktop or Colima on macOS.
• The Docker Compose plugin if you use docker compose.
• A browser.

On macOS, installing only the docker CLI does not start a container engine.

Pull and start the published image:

Docker Hub repository: arulprasath36/qalens

docker volume create qalens-data
docker run --rm \
  -p 127.0.0.1:8080:8080 \
  -v qalens-data:/data \
  arulprasath36/qalens:latest

Open http://127.0.0.1:8080.

The named volume stores:

/data/qalens.db
/data/config.toml

From a source checkout, build and run the current code:

docker compose up --build

See Docker for ingestion commands, upgrades, authentication, and deployment notes.

Install From Source

Use this when developing QA Lens or testing unreleased changes.

git clone https://github.com/Arulprasath36/QALens.git
cd QALens

python3 -m venv .venv
source .venv/bin/activate

pip install -e ".[dev]"
make build-ui

make build-ui compiles the React app into the backend static directory. It is required when serving the UI from a source checkout.

Python Requirements

QA Lens supports Python 3.10 and newer.

Core dependencies include:

• FastAPI and Uvicorn for the web server.
• Typer and Rich for the CLI.
• Pydantic for data models.
• BeautifulSoup and lxml for HTML/XML parsing.
• defusedxml for safer XML parsing.
• httpx for optional LLM provider calls.
• SQLite through the Python standard library.

Node Requirements For Development

Frontend development requires:

• Node.js 18 or newer.
• npm.

Install frontend dependencies:

cd frontend
npm install

Run frontend type checking:

npm run typecheck

Build the frontend:

npm run build

From the repository root, make build-ui is the normal build entrypoint.

Database Location

Default database:

~/.qalens/qalens.db

Recommended explicit local database for demos and CI artifacts:

qalens ingest path/to/report --db ./qalens.db
qalens serve --db ./qalens.db

QA Lens uses SQLite. You do not need PostgreSQL, MySQL, Redis, or any external database.

Configuration Location

Default LLM configuration:

~/.qalens/config.toml

Configure interactively:

qalens llm-config

Or use the Settings page in the UI.

Optional LLM Requirements

QA Lens does not require an LLM for core analysis.

Optional local providers:

• Ollama
• LM Studio
• Any OpenAI-compatible localhost endpoint

Optional cloud providers:

• OpenAI
• Azure OpenAI
• Anthropic
• Gemini
• Custom OpenAI-compatible endpoint

Cloud providers require explicit opt-in. See Chat and LLMs.

Common Install Problems

qalens: command not found

The package is not installed in the active environment, or the virtual environment is not activated.

Check:

which python
which qalens
python -m pip show qalens

UI assets missing from source install

Run:

make build-ui

Python dependency conflicts

Create a clean virtual environment:

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install qalens