Installation
Install the Qontinui Python library for model-based GUI automation
Requirements
Qontinui is a Python library for model-based GUI automation with intelligent state management and visual recognition. Before installing, make sure your environment meets these requirements:
- Python 3.12+
Qontinui targets Python 3.12 and newer. Earlier versions are not supported.
- Native dependencies
Installation pulls in PyTorch, OpenCV (headless), and Hugging Face Transformers, plus input-control libraries (PyAutoGUI, pynput). These are installed automatically.
- Cross-platform
Works on Windows, macOS, and Linux.
Install from PyPI
The recommended way to install Qontinui is from PyPI using pip. This installs the qontinui package along with all of its runtime dependencies.
pip install qontinuiTip: Because Qontinui depends on PyTorch and other large native packages, installing inside a dedicated virtual environment is strongly recommended:
python -m venv .venv
# macOS / Linux
source .venv/bin/activate
# Windows (PowerShell)
.venv\Scripts\Activate.ps1
pip install qontinuiInstall from Source
For development, or to track the latest changes, install from the GitHub repository. Qontinui uses Poetry to manage dependencies.
git clone https://github.com/qontinui/qontinui.git
cd qontinui
# Install with Poetry (recommended for development)
poetry install
# Or with pip in editable mode
pip install -e .The Poetry install also wires up two sibling path dependencies that ship with the project: qontinui-schemas (shared type definitions) and multistate (the multi-state state-management library).
Optional Extras
Qontinui defines a few optional dependency groups (extras) for advanced features. Enable them with Poetry when you need them:
# UI-TARS quantization support (local inference on consumer GPUs)
poetry install -E uitars
# Local embeddings via sentence-transformers
poetry install -E embeddings
# PaddleOCR as an alternative OCR engine for OmniParser
poetry install -E omniparserNote: SAM3 segmentation support must be installed manually and is not available as a Poetry extra: pip install git+https://github.com/facebookresearch/sam3.git
Verify the Installation
Confirm Qontinui imports correctly and check the installed version:
python -c "import qontinui; print(qontinui.__version__)"A successful install also exposes the qontinui command-line entry point:
qontinui --help