🌟

Let’s Run ZundaGPT2 Lite on Raspberry Pi, Linux Mint, and Ubuntu!

に公開
AI
Linux
Python
Raspberry Pi
OpenAI
idea

title image

ZundaGPT2 Lite

ZundaGPT2 Lite is a lightweight chat client application that lets you interact with AI using APIs provided by OpenAI, Google Gemini, Anthropic Claude, and others.
While there is a full-featured sister app, ZundaGPT2, this Lite version is streamlined by removing the voice output function for users who prefer a lighter and faster experience.

Since March 2024, ZundaGPT2 Lite was initially released as a Windows application on GitHub. However, starting from version v1.21.0, it now also supports Raspberry Pi OS Bookworm and Linux Mint/Ubuntu.

This article provides a step-by-step guide for using the Raspberry Pi and Linux versions of ZundaGPT2 Lite.

https://github.com/led-mirage/ZundaGPT2Lite

🍉 Prerequisites

🪴 Registering API Keys

Register your API keys as environment variables in files like ~/.bashrc, ~/.profile, or ~/.xsessionrc.

# API Keys
export OPENAI_API_KEY="xxx"
export GEMINI_API_KEY="yyy"
export ANTHROPIC_API_KEY="zzz"
File Use Case
~/.bashrc When starting from the terminal or via SSH
~/.profile When logging in locally to the desktop
~/.xsessionrc When connecting via RDP

🪴 pyenv + Python 3.12.0

If you run the app as a Python script (rather than as an executable), using pyenv can be convenient.

pyenv is not strictly required, but the code examples in this article assume you are using it.
If you use pyenv, install Python 3.12.0 with:

# Install Python 3.12.0
pyenv install 3.12.0

If you do not use pyenv, please substitute python in the code examples with python3 or whatever matches your environment.

For more information on installing pyenv, see my guide:
"How to Install and Use pyenv"

🪴 Font Installation (Optional)

ZundaGPT2 Lite uses emoji in some screens. If the display looks strange, you may want to install additional fonts:

# Install Japanese fonts (includes emoji support)
sudo apt install fonts-noto fonts-noto-cjk fonts-noto-cjk-extra fonts-noto-color-emoji

🎈 Raspberry Pi

Environment: Raspberry Pi OS Bookworm 64bit, X11/LXDE
Limitations: For Japanese input, only IBus is supported. Printing is not supported.

🎬 Using the Executable File

  1. Download
    Download ZundaGPT2Lite_x.x.x_raspberrypi_arm64.zip from the GitHub Releases page and extract it to a directory of your choice.

  2. Run
    Double-click ZundaGPT2Lite to launch it.
    If you get a permissions error, run chmod +x ZundaGPT2Lite to grant execute permission.

🎬 Running with Python

First Time (Install & Run)

# Clone the repository
git clone https://github.com/led-mirage/ZundaGPT2Lite.git

# Move to the project directory
cd ZundaGPT2Lite

# Create a Python virtual environment
python -m venv venv

# Activate the virtual environment
. venv/bin/activate

# Install dependencies
pip install -r requirements_linux.txt

# Install X11-related packages
sudo apt install libxcb-xinerama0 libxcb-cursor0

# Create symbolic links (for compatibility)
sudo ln -s /usr/lib/aarch64-linux-gnu/libwebp.so.7 /usr/lib/aarch64-linux-gnu/libwebp.so.6
sudo ln -s /usr/lib/aarch64-linux-gnu/libtiff.so.6 /usr/lib/aarch64-linux-gnu/libtiff.so.5

# Run the app
python app/main.py

Subsequent Runs

cd ZundaGPT2Lite
. venv/bin/activate
python app/main.py

Build (Create Executable)

cd ZundaGPT2Lite
. venv/bin/activate
pip install pyinstaller
chmod +x build.sh
./build.sh

🎈 Linux Mint / Ubuntu

Tested Environments:

  • Linux Mint 22.1 Cinnamon Edition
  • Ubuntu 24.04.2 Desktop

Limitations: For Japanese input, only IBus is supported. Printing is not supported.

🎬 Using the Executable File

  1. Download
    Download ZundaGPT2Lite_x.x.x_linux_x64.zip from the GitHub Releases page and extract it to a directory of your choice.

  2. Run
    Double-click ZundaGPT2Lite to launch it.
    If you get a permissions error, run chmod +x ZundaGPT2Lite.

🎬 Running with Python

First Time (Install & Run)

git clone https://github.com/led-mirage/ZundaGPT2Lite.git
cd ZundaGPT2Lite
python -m venv venv
. venv/bin/activate
pip install -r requirements_linux.txt
sudo apt install libxcb-xinerama0 libxcb-cursor0
python app/main.py

Subsequent Runs

cd ZundaGPT2Lite
. venv/bin/activate
python app/main.py

Build (Create Executable)

cd ZundaGPT2Lite
. venv/bin/activate
pip install pyinstaller
chmod +x build.sh
./build.sh

🎈 WSL2

Environment: Ubuntu 24.04.2 LTS
Limitations: Japanese input is not supported. Printing is not supported.

🎬 Running with Python

First Time (Install & Run)

git clone https://github.com/led-mirage/ZundaGPT2Lite.git
cd ZundaGPT2Lite
python -m venv venv
. venv/bin/activate
pip install -r requirements_linux.txt
export QT_QUICK_BACKEND=software
python app/main.py

Subsequent Runs

cd ZundaGPT2Lite
. venv/bin/activate
export QT_QUICK_BACKEND=software
python app/main.py

🗨️ Extra: Challenges When Running on Raspberry Pi

🖊️ Choosing a UI Toolkit

For the GUI of ZundaGPT2/Lite, I use PyWebView. PyWebView itself relies on either QT or GTK as a backend on Linux, so you need to install one or the other.

PyWebView’s documentation suggests the following installation methods, but on Raspberry Pi, installation failed due to source build errors during pip install.

pip install pywebview[gtk]      # Use GTK
pip install pywebview[qt]       # Use PyQt6

I tried installing additional packages to resolve the build errors, but both GTK and QT options ran into environment-specific problems, so I was unable to install them successfully.

As an alternative, I chose PySide6.
PySide6 is officially maintained and distributed by the QT project, so it works out-of-the-box on many environments, including Raspberry Pi, without any build required. PyWebView automatically recognizes PySide6 as a QT backend.

To install both PyWebView and PySide6 together:

pip install pywebview[pyside6]

Or, to install only PySide6:

pip install pyside6 qtpy

As of June 27, 2025, the latest version of PySide6 available via pip is 6.8.0.2. Unfortunately, this version is not compatible with Debian 12 Bookworm.
PySide6 relies on libwebp and libtiff, but the required versions are not available in Bookworm, which leads to runtime errors.

To work around this, the instructions above use symbolic links. For example, if PySide6 asks for libwebp version 6, but only version 7 is available, the symbolic link redirects the request to the available version. The same applies for libtiff.

However, the upcoming PySide6 version 6.8.1 should support Arm-based Bookworm natively, so this workaround may soon become unnecessary.

To remove the symbolic links:

sudo rm /usr/lib/aarch64-linux-gnu/libwebp.so.6
sudo rm /usr/lib/aarch64-linux-gnu/libtiff.so.5

🖊️ About Japanese Input

There are two main frameworks for Japanese input: IBus and Fcitx5.
Recently, Fcitx5 has become more common.

At first, I tried to use Fcitx5, but I couldn’t switch to Japanese input mode in the text boxes. After much trial and error, I found that IBus worked fine, so I decided to use it.

The reason why Japanese input doesn't work with Fcitx5 is probably due to a compatibility issue with QT, but I’m not sure. In any case, if you use IBus, everything works as expected—so I recommend sticking with it.

📝 Summary

In this article, I explained how to run ZundaGPT2 Lite on various Linux-based operating systems.

ZundaGPT2 Lite is a lightweight version of ZundaGPT2 with the voice output feature removed, but it still includes essential features like character settings, chat log management, and Markdown rendering—just like the full version.
I hope you’ll find it useful not only for fun, but also for learning and work. Please give it a try!

That’s all for now. See you somewhere in the digital world.
Bye for now! 😊

Discussion