Xonsh Flatpak

Flatpak bundle for xonsh 0.22.8 — a Python-powered, cross-platform, Unix-gazing shell.

Built on org.freedesktop.Platform / org.freedesktop.Sdk 24.08 (Python 3.12).

Quick Install

flatpak install --user xonsh.flatpak
flatpak run io.github.xonsh.xonsh

Bundled Python Packages

Package	Version
xonsh	0.22.8
prompt-toolkit	3.0.52
pygments	2.20.0
pyperclip	1.11.0
distro	1.9.0
wcwidth	0.6.0

Project Structure

io.github.xonsh.xonsh.yml          # Flatpak manifest
io.github.xonsh.xonsh.desktop      # Desktop entry
io.github.xonsh.xonsh.metainfo.xml # AppStream metadata
io.github.xonsh.xonsh.svg          # Application icon (SVG)
xonsh-wrapper.py                    # Entry point: patches termios EINTR + sets up PATH
xonsh-flatpak.sh                    # Shell wrapper that launches xonsh-wrapper.py
flatpak-xonshrc.py                  # Optional xonshrc with `host` alias
host-spawn                          # Generic wrapper: forwards commands to host via flatpak-spawn
xonsh.flatpak                       # Pre-built bundle (ready to install)

Building from Source

Prerequisites

Ubuntu 24.04 (or similar):

sudo apt-get update
sudo apt-get install -y flatpak flatpak-builder

Add the Flathub remote and install the runtime + SDK:

flatpak remote-add --user --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
flatpak install --user -y flathub org.freedesktop.Platform/x86_64/24.08
flatpak install --user -y flathub org.freedesktop.Sdk/x86_64/24.08

Build

flatpak-builder --user --force-clean build-dir io.github.xonsh.xonsh.yml

Export as .flatpak Bundle

# Export to a local Flatpak repo
flatpak-builder --user --repo=repo --force-clean build-dir io.github.xonsh.xonsh.yml

# Create a single-file bundle
flatpak build-bundle repo xonsh.flatpak io.github.xonsh.xonsh

This produces xonsh.flatpak (~1.9 MB) that can be installed on any system with Flatpak and the org.freedesktop.Platform//24.08 runtime.

Install and Run

flatpak install --user xonsh.flatpak
flatpak run io.github.xonsh.xonsh

Uninstall

flatpak uninstall --user io.github.xonsh.xonsh

Flatpak-Specific Details

termios EINTR Patch

The Flatpak sandbox (bubblewrap) can deliver signals during terminal setup, causing termios.tcsetattr to fail with EINTR. The xonsh-wrapper.py entry point monkey-patches termios.tcsetattr and termios.tcgetattr to automatically retry on EINTR, preventing the crash in prompt-toolkit's raw mode initialization.

Host Command Forwarding

The Freedesktop Platform runtime includes ~728 standard Unix commands (ls, cat, grep, curl, etc.), but system-specific tools like git, docker, ssh are not available inside the sandbox.

To solve this, the build creates symlinks in /app/libexec/host-cmds/ pointing to the host-spawn script, which forwards commands to the host system via flatpak-spawn --host. These symlinks are added to $PATH by the wrapper.

Pre-configured host-forwarded commands include: git, docker, podman, ssh, rsync, systemctl, apt, dnf, pacman, node, npm, go, cargo, make, cmake, gcc, vim, nvim, nano, tmux, and more.

For any other host command, use the host alias (loaded from flatpak-xonshrc.py if placed in ~/.config/xonsh/rc.d/):

host mycommand --flag

Or call flatpak-spawn directly:

flatpak-spawn --host mycommand --flag

Sandbox Permissions

Permission	Reason
--share=network	Network access for shell commands
--share=ipc	IPC for clipboard (pyperclip)
--device=all	Full device access for terminal operations
--filesystem=home	Read/write access to user home directory
--filesystem=/tmp	Access to /tmp for temp files
--filesystem=host:ro	Read-only access to host filesystem
--talk-name=org.freedesktop.Flatpak	D-Bus access for flatpak-spawn --host

License

xonsh is licensed under the BSD-2-Clause license.