voculinux/docs/DISTRO_COMPATIBILITY.md

Linux distribution compatibility

How Voculinux behaves across distributions, what is tested, and what to install manually when needed.

The published package targets Void Linux (glibc, x86_64). It is the only Voculinux package this project publishes: a signed xbps repository, registered as described in INSTALL.md. The distribution tables below describe source-checkout builds with install.sh, for developers. They are not published packages.

For install steps, prefer INSTALL.md.

Cross-distro behavior

For source checkouts, the installer and launch wrappers handle most path differences.

GI_TYPELIB_PATH detection

The installer uses a multi-step approach to detect the correct GI_TYPELIB_PATH:

1. Primary Method: Uses pkg-config --variable=typelibdir gobject-introspection-1.0 (most reliable)

2. Fallback Paths: Checks common distribution-specific paths in priority order:

   • Ubuntu/Debian multi-arch: /usr/lib/x86_64-linux-gnu/girepository-1.0
   • ARM64: /usr/lib/aarch64-linux-gnu/girepository-1.0
   • Fedora/RHEL: /usr/lib64/girepository-1.0
   • Arch/Generic: /usr/lib/girepository-1.0
   • Local installs: /usr/local/lib/girepository-1.0

3. Architecture Support: Detected paths for x86_64, ARM64, ARMHF, RISC-V, POWER, and s390x

Wrapper Scripts

The source installer creates wrapper scripts (~/.local/bin/voculinux and ~/.local/bin/voculinux-gui) that:

• Set the correct GI_TYPELIB_PATH environment variable
• Handle input group permissions for Wayland keyboard shortcuts
• Provide seamless cross-distro compatibility

Desktop Entry

For source installs, the .desktop entry is automatically configured with the detected GI_TYPELIB_PATH, ensuring the application launches correctly from the application menu regardless of distribution.

Officially Supported Distributions (source checkouts)

For source-checkout builds with install.sh, these distributions are tested and known to work well with Voculinux. A derivative is judged by the Python and package repositories it ships rather than by its own version number, which rarely tracks the base release. In particular, install.sh does not interpret a Debian-based derivative's product version as a Debian release number.

Distribution	Version	Status	Notes
Ubuntu	24.04+	✅ Full Support	22.04 ships Python 3.10, below the 3.11 floor
Debian	12+, Testing	✅ Full Support	Primary target; use Ayatana AppIndicator
Fedora	42+	✅ Good Support	Uses lib64 paths; 42 is the oldest Fedora upstream still supports, and the one in the CI matrix
Arch Linux	Rolling	✅ Good Support	Community tested, rolling release compatible
openSUSE	Tumbleweed	✅ Good Support	Good support with zypper package manager
Linux Mint	On Ubuntu 24.04+	✅ Good Support	Mint 22 qualifies; Mint 21 is on Ubuntu 22.04, below the floor
Pop!_OS	24.04+	✅ Good Support	Uses Ubuntu's own numbering
elementary OS	On Ubuntu 24.04+	✅ Good Support	elementary 8 qualifies; 7 is on Ubuntu 22.04
Zorin OS	On Ubuntu 24.04+	✅ Good Support	Zorin 17 is on Ubuntu 22.04, below the floor
Manjaro	Rolling	✅ Good Support	Arch base, inherits Arch compatibility
EndeavourOS	Rolling	✅ Good Support	Arch base, inherits Arch compatibility

Experimental Support

These distributions may work but have known limitations or are less tested:

Distribution	Status	Known Issues
Gentoo	⚠️ Experimental	No package manager support, manual install required. Packages are compiled from source which takes longer.
Alpine Linux	⚠️ Experimental	Uses musl libc (not glibc). Some Python packages may not have pre-built wheels and may need to be compiled.
Void Linux	⚠️ Experimental	Source-checkout builds are untested here. The published xbps package is the supported route; see Void Linux.
Solus	⚠️ Experimental	Untested, manual install required. Uses eopkg package manager.
Mageia	⚠️ Experimental	Untested, uses dnf/urpmi package managers.

Not Supported

These distributions are known to be incompatible:

Distribution	Status	Reason
Debian 11 and earlier	❌ Not Supported	EOL and below the Python 3.11 floor; the installer requires Debian 12+
NixOS	❌ Not Supported	Completely different filesystem layout (/nix/store), incompatible with standard installer

Requirements by Distribution

These are baseline commands for source-checkout builds. The exact inventory used by install.sh, including package alternatives and conditional dependencies, lives in scripts/distro-package-map.yaml. For the complete developer setup sequence, including native build prerequisites, see CONTRIBUTING.md.

Ubuntu/Debian-based

sudo apt install -y python3-gi gir1.2-gtk-3.0 gir1.2-ibus-1.0 gir1.2-gdkpixbuf-2.0 \
  portaudio19-dev python3-dev python3-venv pkg-config

Note for Debian 12+: Use gir1.2-ayatanaappindicator3-0.1 instead of gir1.2-appindicator3-0.1

Debian-specific notes

Debian's standard repositories differ from Ubuntu in a few ways that matter for Voculinux:

pywhispercpp build prerequisites. On a clean Debian install the following packages are not pulled in transitively (unlike Ubuntu) but are required when pywhispercpp must be compiled from source (e.g. for GPU support):

sudo apt install -y libssl-dev autoconf automake libtool patchelf

The installer now installs these automatically, but if you hit a CMake error like Could not find OpenSSL during a manual reinstall, add the above first.

ydotool. ydotool is not packaged in Debian's standard repos. The installer falls back gracefully to IBus or wtype for most Wayland compositors. KDE Plasma Wayland users should first select IBus Wayland in System Settings -> Keyboard -> Virtual Keyboard. If you specifically need ydotool as a fallback, compile it from source:

sudo apt install -y git cmake libevdev-dev
git clone https://github.com/ReimuNotMoe/ydotool.git /tmp/ydotool
cmake -S /tmp/ydotool -B /tmp/ydotool/build
sudo cmake --build /tmp/ydotool/build --target install
sudo systemctl enable --now ydotoold

Scoped source builds. If you need to force pywhispercpp to rebuild from source, use the installer's flag. It rebuilds the whisper.cpp bindings and leaves the rest of the venv alone, so unrelated dependencies such as NumPy are not compiled from source:

./install.sh --auto --rebuild-whispercpp

Verifying libwhisper.so resolution. If Voculinux starts with libwhisper.so.1: cannot open shared object file, check for unresolved symbols:

ldd $(find venv -name '*.so' -path '*/pywhispercpp*' 2>/dev/null | head -1) | grep 'not found'

If any libraries are listed, re-run the installer with --rebuild-whispercpp or switch to the VOSK engine (--engine=vosk) as an alternative.

Fedora/RHEL-based

sudo dnf install -y python3-gobject gtk3-devel ibus-devel cairo-devel gobject-introspection-devel \
  portaudio-devel python3-devel python3-virtualenv pkg-config

Arch Linux-based

sudo pacman -S --needed python-gobject gtk3 ibus gobject-introspection \
  portaudio python pkg-config

openSUSE

PYVER=$(python3 -c 'import sys; print(f"python{sys.version_info.major}{sys.version_info.minor}")')

sudo zypper install -y \
  "${PYVER}-pip" "${PYVER}-gobject" "${PYVER}-gobject-cairo" \
  "${PYVER}-devel" "${PYVER}-virtualenv" \
  gtk3 ibus typelib-1_0-IBus-1_0 \
  typelib-1_0-AyatanaAppIndicator3-0_1 libayatana-appindicator3-1 \
  typelib-1_0-Notify-0_7 libnotify4 \
  gobject-introspection-devel portaudio-devel pkg-config cmake wget curl unzip \
  gcc gcc-c++ make patchelf \
  xdotool wtype

# Optional: only needed for whisper.cpp Vulkan GPU builds
sudo zypper install -y vulkan-tools vulkan-devel shaderc

Note: openSUSE Tumbleweed often uses versioned Python package names such as python313-devel. The -devel suffix means development headers for compiling native dependencies; it does not mean beta or unstable packages. If ${PYVER}-virtualenv is unavailable on your snapshot, try ${PYVER}-venv.

Gentoo

sudo emerge dev-python/pygobject:3 x11-libs/gtk+:3 dev-libs/libayatana-appindicator \
  media-libs/portaudio dev-lang/python:3.11

Note: Gentoo compiles packages from source, which will take longer.

Alpine Linux

sudo apk add py3-gobject3 py3-pip gtk+3.0 py3-cairo portaudio-dev \
  py3-virtualenv pkgconf

Note: Alpine uses musl libc. Some Python packages may need to be compiled from source.

Void Linux

The published Voculinux package for Void is described in INSTALL.md. This section covers source-checkout builds on Void, which are experimental. Packages from the install.sh inventory:

sudo xbps-install -S python3-pip python3-gobject gtk+3 libayatana-appindicator \
  gobject-introspection portaudio-devel cairo-devel python3-devel pkg-config cmake \
  base-devel wget curl unzip shaderc patchelf Vulkan-Tools xclip xsel wl-clipboard \
  xdotool wtype

Note: ydotool is not packaged for Void, so the ydotool injection fallback rung is unavailable there. On niri, text is typed directly through wtype with no permission prompt. IBus is not used on niri. On GNOME and KDE the RemoteDesktop portal is tried first where it is available.

Solus

sudo eopkg install python3-pip python3-gobject gtk3 libappindicator \
  gobject-introspection-devel portaudio-devel python3-virtualenv pkg-config

Mageia

sudo dnf install -y python3-gobject gtk3-devel gobject-introspection-devel \
  portaudio-devel python3-devel python3-virtualenv pkg-config
# or
sudo urpmi -y python3-gobject gtk3-devel gobject-introspection-devel \
  portaudio-devel python3-devel python3-virtualenv pkg-config

Text Injection Tools

Voculinux requires text injection tools to work with X11 or Wayland:

For X11

• xdotool: Required for X11 sessions

For Wayland

• IBus: Recommended for KDE Plasma Wayland and generally the most reliable direct text input path
• wtype: Recommended for wlroots-style Wayland compositors such as sway
• ydotool: Universal alternative that works with both X11 and Wayland. Current distro packages use the per-user ydotool.service; source builds can install the system-level ydotoold.service. Voculinux uses clipboard paste with wl-clipboard, xclip, or xsel to avoid non-US layout scrambling.
• xdotool: May work via XWayland fallback

Installation by Distribution

# Void/Ubuntu/Debian/Fedora/Arch/openSUSE
sudo xbps-install -S xdotool wtype wl-clipboard xclip xsel # Void
sudo apt install xdotool wtype wl-clipboard xclip xsel     # Ubuntu/Debian
sudo dnf install xdotool wtype wl-clipboard xclip xsel     # Fedora
sudo pacman -S xdotool wtype wl-clipboard xclip xsel       # Arch
sudo zypper install xdotool wtype wl-clipboard xclip xsel  # openSUSE

Ubuntu releases which package ydotool install a user unit named ydotool.service. Enable it only for the account running Voculinux:

sudo apt install ydotool
sudo usermod -aG input $USER  # then log out and back in
systemctl --user enable --now ydotool.service

Do not use sudo systemctl --global enable ydotool.service. Global user-unit enablement also starts the input-injection daemon for the display-manager greeter and other accounts. If it was previously enabled globally, repair the setup with:

sudo systemctl --global disable ydotool.service
systemctl --user enable --now ydotool.service

The command is different for the Debian source-build path documented above: the upstream install supplies the system unit ydotoold.service, so sudo systemctl enable --now ydotoold.service is correct only for that route.

Manual Installation

For unsupported or experimental distributions:

1. Run the dependency checker:

   bash scripts/check-system-deps.sh
   

2. Install missing dependencies using your package manager based on the checker output

3. Run the installer with --skip-system-deps:

   ./install.sh --skip-system-deps
   

4. Or set up a development checkout with ./install.sh --dev, as described in CONTRIBUTING.md.

Desktop Environment Compatibility

Desktop Environment	Status	Notes
GNOME	✅ Full Support	Primary target, uses AppIndicator
KDE Plasma	✅ Full Support	On Wayland, select IBus Wayland in System Settings -> Keyboard -> Virtual Keyboard
Xfce	✅ Full Support	Works with AppIndicator
Cinnamon	✅ Full Support	Works with AppIndicator
MATE	✅ Full Support	Works with AppIndicator
LXQt	✅ Full Support	Works with AppIndicator
sway	✅ Good Support	Wayland native, uses wtype
i3	✅ Good Support	X11, uses xdotool
Hyprland	⚠️ Experimental	Wayland, may need wtype configuration

Autostart Compatibility

Voculinux uses XDG autostart desktop entries for "Start on Login".

• Desktop-session autostart file location:
  • $XDG_CONFIG_HOME/autostart/voculinux.desktop, or
  • ~/.config/autostart/voculinux.desktop (fallback)
• This launches Voculinux as a user GUI app after login.
• Voculinux does not create a systemd service/unit for this feature.

Practical caveat:

• Mainstream desktop environments generally honor XDG autostart.
• Minimal/custom WM sessions may need an explicit autostart manager or WM startup hook.

Display Server

Display Server	Status	Notes
X11	✅ Full Support	Uses xdotool for text injection
Wayland	✅ Full Support	Uses IBus, wtype, ydotool, or xdotool fallback depending on compositor
XWayland	✅ Full Support	Automatically detected, falls back to xdotool if needed

Architecture Support

Architecture	Status	Notes
x86_64 (AMD64)	✅ Full Support	Primary target
arm64 (AArch64)	✅ Good Support	Tested on Raspberry Pi, ARM64 servers
armhf	⚠️ Experimental	Limited testing
riscv64	⚠️ Experimental	Limited testing, may need to compile dependencies

Reporting Issues

When reporting issues, please include:

1. Distribution information:

   cat /etc/os-release
   

2. Desktop environment:

   echo $XDG_CURRENT_DESKTOP
   echo $SESSION_TYPE
   

3. Dependency checker output:

   bash scripts/check-system-deps.sh
   

4. Python version:

   python3 --version
   

5. Error messages or logs:

   • Any error messages from the installer
   • Output from running voculinux-gui from terminal
   • Relevant journal logs if applicable

6. Steps to reproduce:

   • What you were trying to do
   • What happened instead
   • Expected behavior

Testing Checklist

Use this checklist when testing on a new distribution:

Pre-Install

• Run dependency checker: bash scripts/check-system-deps.sh
• Note missing packages
• Check desktop environment
• Check display server (X11/Wayland)

Installation

• Run installer: ./install.sh
• Check for errors during installation
• Verify virtual environment was created
• Check wrapper scripts exist

Post-Install

• Launch from terminal: ~/.local/bin/voculinux-gui
• Launch from application menu
• Verify tray icon appears
• Test keyboard shortcuts (Hold Right Alt by default)
• Test audio recording
• Test text injection in different applications
• Test Settings dialog opens correctly
• Test model download if using Whisper

Known Issues to Watch For

• AppIndicator not showing in tray
• Audio device not detected
• Text injection not working
• Model download failures
• Permission errors with udev/input

Contributing Compatibility Fixes

If you successfully get Voculinux working on an unsupported or experimental distribution:

1. Test thoroughly using the checklist above
2. Document any distribution-specific requirements
3. Submit a PR with:
   • Distribution detection logic (if needed)
   • Package installation commands
   • Any patches or workarounds required
   • Update to this compatibility document

See also

• Installation guide
• Troubleshooting
• User guide
• Update guide
• Open issues