Skip to content

Installation

brayer can be installed from PyPI or directly from source via GitHub.

It needs Python 3.10+. Its only runtime dependencies are pydantic and pyside6-essentials, both of which ship wheels for every supported platform.

PyPI

For using the PyPI package in your project, add it to your configuration file:

[project]
dependencies = [
    "brayer>=0.1.0", # (1)!
]
  1. Specifying a version is recommended
brayer>=0.1.0

pip

pip install --upgrade --user brayer # (1)!
  1. You may need to use pip3 instead of pip depending on your Python installation.
python -m venv .venv
source .venv/bin/activate
pip install --require-virtualenv --upgrade brayer # (1)!
  1. You may need to use pip3 instead of pip depending on your Python installation.

Note

The command to activate the virtual environment depends on your platform and shell. More info

uv

uv add brayer
uv sync

uv venv
uv pip install brayer

poetry

poetry add brayer

pdm

pdm add brayer

Linux: Qt runtime libraries

PySide6 links a handful of system libraries that most desktop distributions already have, but a container or CI image usually does not. If import brayer fails with an ImportError naming a missing .so, install them:

sudo apt-get install -y --no-install-recommends \
  libegl1 libgl1 libdbus-1-3 libxkbcommon-x11-0 \
  libxcb-cursor0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 \
  libxcb-randr0 libxcb-render-util0 libxcb-shape0 \
  libxcb-xinerama0 libxcb-xkb1

sudo dnf install -y \
  mesa-libEGL mesa-libGL dbus-libs libxkbcommon-x11 \
  xcb-util-cursor xcb-util-wm xcb-util-image \
  xcb-util-keysyms xcb-util-renderutil

Running without a display

Set Qt's offscreen platform before anything Qt is imported. Widgets are then built and read entirely in memory:

export QT_QPA_PLATFORM=offscreen

This is how this project's own test suite runs, so the whole library is exercised headlessly on every CI leg.

Fonts under offscreen

Some minimal images expose no font database at all, and text renders as empty boxes. Install any font package — fonts-dejavu-core on Debian — if you intend to capture screenshots.

GitHub

Install the latest development version directly from the repository:

pip install --upgrade "git+https://github.com/eggzec/brayer.git#egg=brayer"

Building locally

Clone and build from source if you want to modify or test local changes:

git clone https://github.com/eggzec/brayer.git
cd brayer
uv sync            # or: pip install -e .
uv run pytest      # the suite runs headlessly