Linux Browser

A small graphical browser for Linux, packaged as a normal Python application. It uses Qt WebEngine, which embeds Chromium, so pages are rendered with their real HTML, CSS, JavaScript, images, and network behavior rather than being converted to terminal text.

Debian 12 / Ubuntu Installation

Dependencies

Install graphics and browser libraries:

sudo apt update
sudo apt install -y \
  libgl1 libegl1 \
  libxkbcommon-x11-0 libxcb-cursor0 \
  libxcomposite1 libxdamage1 libxrandr2 \
  libnss3 libxshmfence1 libxtst6 \
  libasound2t64 xvfb xdg-utils

The PyPI wheels provide the Qt and Chromium components. A working display or Xvfb (virtual framebuffer) is required to render pages.

Usage

With a graphical display (desktop/GUI environment):

linux-browser https://example.com

Headless (no display server):

QT_QPA_PLATFORM=offscreen xvfb-run -a linux-browser https://example.com

Via SSH or in a container:

export DISPLAY=:99
Xvfb :99 &
linux-browser https://example.com

Install and run

python3 -m venv .venv
.venv/bin/python -m pip install linux-browser
.venv/bin/linux-browser

Open a specific page directly:

linux-browser https://example.com

The address bar accepts URLs and search terms. Back, forward, reload, and common keyboard shortcuts are available in the toolbar.

Development

python3 -m venv .venv
.venv/bin/python -m pip install -e . pytest build
.venv/bin/python -m pytest

The WebEngine test loads an in-memory page and checks that CSS and JavaScript execute (powered by PySide6's built-in WebEngine). It is skipped when PySide6 is not installed, which keeps package metadata checks usable in minimal build environments.

Build and publish

Build the package and validate it before uploading:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip build twine
python -m build
python -m twine check dist/*

Publish with your PyPI API token:

export PYPI_API_TOKEN="pypi-xxxxxxxxxxxxxxxx"
TWINE_USERNAME="__token__" TWINE_PASSWORD="$PYPI_API_TOKEN" python -m twine upload --repository pypi dist/*

You can also use the helper script in this repo:

chmod +x scripts/publish.sh
export PYPI_API_TOKEN="pypi-xxxxxxxxxxxxxxxx"
./scripts/publish.sh

Use the token value from your PyPI account, not your account password. The __token__ username is the standard PyPI format for API tokens.