Installation

Requirements

• Python 3.12+
• pip

Install

pip install quantum-framework

This installs the quantum command and the quantum Python package. Check it:

quantum --version

quantum 0.10.0

Use a virtual environment

python -m venv .venv, then activate it (source .venv/bin/activate, or .venv\Scripts\activate on Windows) before pip install.

Optional extras

The base install covers components, the web server, SQLite queries and the terminal target. Everything else is an extra:

Extra	Install	Adds
db	pip install "quantum-framework[db]"	PostgreSQL and MySQL drivers for q:query
rag	pip install "quantum-framework[rag]"	Vector store for q:knowledge / RAG queries
jobs	pip install "quantum-framework[jobs]"	Scheduler behind q:schedule
websocket	pip install "quantum-framework[websocket]"	Transport behind q:websocket

Extras combine: pip install "quantum-framework[db,jobs]".

The desktop target also needs pip install pywebview (on Linux, pywebview has system dependencies of its own — see its documentation).

The AI tags (q:llm, q:knowledge, q:agent) talk to an Ollama server — http://localhost:11434 unless QUANTUM_LLM_BASE_URL says otherwise.

See SUPPORT_TIERS.md for which of these are stable and which are experimental.

Verify

Create hello.q:

<q:component name="HelloWorld" xmlns:q="https://quantum.lang/ns">
  <q:return value="Hello World!" />
</q:component>

quantum run hello.q

[EXEC] Executing component: HelloWorld
[SUCCESS] Result: Hello World!

Web server

Put components in a components/ folder and start the server from the folder that contains it:

myapp/
└── components/
    └── index.q      # served at /

quantum start               # http://localhost:8080
quantum start --port 9000   # another port
quantum stop                # stops the server started above

components/orders.q is served at /orders, and so on.

Configuration

Settings live in quantum.config.yaml, next to components/. Datasources for q:query:

datasources:
  db:
    driver: sqlite
    database: ./data/app.db

Keep secrets out of the file by referencing environment variables. ${NAME:-default} falls back to a default, and $$ is a literal $:

datasources:
  db:
    driver: postgres
    host: ${DB_HOST:-localhost}
    password: ${DB_PASSWORD}

If DB_PASSWORD is not set, Quantum refuses to start and says which variable and which setting.

From source

To work on Quantum itself:

git clone https://github.com/danielgregorio/quantum.git
cd quantum
pip install -e ".[dev,db,jobs,websocket]" -r quantum_admin/backend/requirements.txt
pytest

The docs site is built from the repository root:

npm ci
npm run docs:dev

CONTRIBUTING.md covers the architecture and how to add a tag.

Troubleshooting

quantum: command not found — the environment where you ran pip install is not active, or its Scripts/bin folder is not on PATH. python -m quantum.cli.runner --version works either way.

XML parse errors — a .q file is XML: every tag closes, attributes are quoted, and <, >, & in text are written <, >, &. The error names the line and column.

Port 8080 already in use — another server is running. quantum stop, or quantum start --port <other>.

Next steps

• Quick Start — build your first app
• Components — the component system
• Help and issues