Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/StarTrail-org/PixelRAG/llms.txt

Use this file to discover all available pages before exploring further.

PixelRAG is a Python package (≥ 3.12) distributed on PyPI under the name pixelrag. The core install is intentionally lightweight — it gives you the pixelshot renderer and the pixelrag CLI without pulling in PyTorch or FAISS. Heavier stages like embedding and serving are opt-in extras so you only install the dependencies your use case actually needs.

​
Package extras

Each extra activates a distinct part of the pipeline. Install one, several, or all of them depending on what you intend to run.
ExtraWhat it includesUse when
(none / core)pixelshot renderer, Chrome DevTools Protocol capture, PyMuPDFRendering URLs and PDFs to tiles only
embedtorch, torchvision, transformers, faiss-cpuBuilding embeddings from rendered tiles
servefastapi, uvicorn, faiss-cpu, transformers, torch, torchvision, qwen-vl-utils, pydanticRunning the local search server
indexembed + markdownFull pipeline orchestration via pixelrag index build
qdrantqdrant-clientUsing Qdrant as the vector backend instead of FAISS
allembed + serve + index + qdrantEverything except GPU and optional format extras
gpufaiss-gpu-cu12 (Linux only)GPU-accelerated FAISS on Linux with CUDA 12
pdfpdf2imagePDF rendering via poppler (alternative to the PyMuPDF path)
kiwixlibzimIngesting Kiwix ZIM file sources
distributedboto3Distributed operations and S3-backed sources
evalpandas, openai, datasets, huggingface-hub, trafilatura, aiohttp, PillowRunning evaluation benchmarks

​
Installation commands

Pick the extras that match your workflow. You can always add more later by re-running pip install with the new extra set. 
pip install pixelrag
If you use uv and want pixelshot available globally on your PATH without affecting a project virtual environment, install it as a tool: 
uv tool install pixelrag
The Claude pixelbrowse plugin requires pixelshot to be on your PATH. Installing with uv tool install or pipx install guarantees this regardless of which virtual environment is currently active.

​
Platform notes

​
Linux

Linux is the primary platform and is fully supported for all pipeline stages.
  • CUDA GPU acceleration — Install the gpu extra (pip install 'pixelrag[gpu]') to swap faiss-cpu for faiss-gpu-cu12. PyTorch is pulled from the pytorch-cu129 index automatically when running on Linux, giving you CUDA 12.9 / cuDNN 9.20 support.
  • Bundled headless Chrome — On linux-x64, pixelshot automatically installs a patched turbo headless_shell binary for fast CDP rendering. No separate Chrome installation is needed.
  • Multi-GPU embedding — Pass --gpu-ids 0,1 (or more IDs) to pixelrag embed to distribute the embedding workload across multiple CUDA devices.

​
macOS (Apple Silicon)

macOS with Apple Silicon (M-series) is fully supported for rendering and index building.
  • MPS device — When device: auto is set in pixelrag.yaml (or passed to the embed stage), PixelRAG selects the MPS backend on macOS for PyTorch operations, giving GPU-accelerated embedding without CUDA.
  • System Chrome — There is no bundled headless shell for macOS. pixelshot auto-detects your system Chrome or Chromium from standard install locations. If it isn’t found, set CHROME_PATH (see below).

​
Windows

The core rendering stage works on Windows using your system Chrome installation.
  • pixelshot auto-detects Chrome from the standard Windows install paths. If detection fails, set the CHROME_PATH environment variable to point at your chrome.exe.
  • The gpu extra (faiss-gpu-cu12) is Linux-only and will not install on Windows.
  • All other extras (serve, index, embed, etc.) install normally on Windows, though the embedding stage has only been tested with CPU and CUDA on Linux.

​
Chrome and Chromium

PixelRAG renders pages through a real browser (Chrome/Chromium) using the Chrome DevTools Protocol (CDP). The table below summarises how the binary is resolved on each platform.
PlatformHow Chrome is found
linux-x64A patched turbo headless_shell is downloaded and cached automatically on first use.
macOSAuto-detected from /Applications/Google Chrome.app and other standard locations, or Playwright’s Chromium.
WindowsAuto-detected from %LOCALAPPDATA%\Google\Chrome\Application\chrome.exe and common locations.
AnySet CHROME_PATH=/path/to/chrome to point at a specific binary and bypass auto-detection.
Each render runs in an isolated, throwaway Chrome profile — it is safe to run pixelshot while Chrome is already open.
The playwright backend (--backend playwright) requires a separate playwright install chromium step. Install the playwright extra first: pip install 'pixelrag[playwright]', then run playwright install chromium.

​
Verify your installation

After installing, confirm both CLI entry points are available: 
# Check the renderer
pixelshot --help

# Check the pipeline umbrella
pixelrag --help
A successful install prints the help text for each command. If either command is not found, make sure the environment’s bin or Scripts directory is on your PATH, or use uv tool install / pipx install as described above.
To quickly confirm end-to-end rendering works, render the PixelRAG homepage and check that tile files appear in ./tiles:
pixelshot https://pixelrag.ai --output ./tiles
ls ./tiles

Build docs developers (and LLMs) love

Get started for freeTalk to us