Tutorials: How to create an AppImage for your python code

By Mihai Cornel Linux Magazin July 11, 2026

Creating an AppImage for a Python/Tkinter application is a multi-step process. Since AppImages require a compiled binary or a bundled runtime, the easiest and most reliable method is to first compile the Python script into a standalone executable using PyInstaller, and then package that executable into an AppImage using AppImageTool.

Here is the step-by-step guide to creating an AppImage for the Python-Tkinter-Calculator repository.

Step 1: Clone the Repository

First, download the source code to your local machine and navigate into the directory.

Bash

git clone https://github.com/mhcrnl1/Python-Tkinter-Calculator.git
cd Python-Tkinter-Calculator

Step 2: Set Up the Environment

It is highly recommended to use a virtual environment so you don't clutter your system's Python packages.

Bash
# Create and activate a virtual environment
python3 -m venv venv
source venv/bin/activate

# Install PyInstaller
pip install pyinstaller

(Note: If the repository contains a requirements.txt file, run pip install -r requirements.txt as well. Tkinter is usually included with standard Linux Python installations).

Step 3: Build the Standalone Executable

Look inside the repository folder to find the main Python file that launches the calculator (e.g., main.py, calculator.py, or similar). Use PyInstaller to build it.

We will use --windowed to prevent a terminal console from popping up behind the Tkinter GUI, and --onefile to bundle everything into a single binary.

Bash

# Replace 'main_script.py' with the actual name of the calculator's launch script
pyinstaller --onefile --windowed main_script.py

This process will create a dist folder containing your compiled executable.

Step 4: Prepare the `AppDir` Structure

An AppImage requires a specific directory structure known as an AppDir. Let's create it and move our new executable inside.

Bash

# Create the directory structure
mkdir -p Calculator.AppDir/usr/bin

# Copy the executable into the AppDir (Replace 'main_script' with your executable's name)
cp dist/main_script Calculator.AppDir/usr/bin/calculator

Step 5: Create the `.desktop` File and AppRun

AppImages need a desktop entry file to know how to integrate with Linux application menus, and an AppRun file (usually a symlink) to know what to execute when double-clicked.

1. Create the Desktop file:

Bash

cat << 'EOF' > Calculator.AppDir/calculator.desktop
[Desktop Entry]
Name=Tkinter Calculator
Exec=calculator
Icon=calculator
Type=Application
Categories=Utility;
EOF

2. Create the AppRun symlink:

Bash

cd Calculator.AppDir
ln -s usr/bin/calculator AppRun
cd ..

Step 6: Add an Icon

The AppImage requires an icon in the root of the AppDir that matches the Icon= value in your desktop file.

Bash

# If the repo has an icon, copy it in. Otherwise, you can download a dummy one for now:
wget -O Calculator.AppDir/calculator.png https://upload.wikimedia.org/wikipedia/commons/2/21/Calculator_icon.png

Step 7: Build the AppImage

Finally, you will use appimagetool to compress the AppDir into a single, distributable .AppImage file.

Bash
# Download appimagetool
wget https://github.com/AppImage/AppImageKit/releases/download/continuous/appimagetool-x86_64.AppImage

# Make it executable
chmod +x appimagetool-x86_64.AppImage

# Build the final AppImage
./appimagetool-x86_64.AppImage Calculator.AppDir

The Result

Once the command finishes, you will see a new file named something like Tkinter_Calculator-x86_64.AppImage in your current directory.

You can now run this file on almost any Linux distribution by simply making it executable and double-clicking it:

Bash

chmod +x Tkinter_Calculator-x86_64.AppImage
./Tkinter_Calculator-x86_64.AppImage

https://drive.google.com/file/d/1TDt8xqq62vV_JpvCq-B7vBniODXEGLnU/view?usp=sharing

To pack your Python Tkinter calculator as an AppImage, you can use a tool called python-appimage or appimagetool combined with a manual layout. The easiest and most reliable way for standalone Python applications is using appimage-builder or the manual AppDir layout.

Here is the step-by-step guide to manually creating an AppImage package for your software on Ubuntu/Linux.

Step 1: Install Necessary Tools

You will need appimagetool to compile your folder into a single executable AppImage file.

Bash
# Download appimagetool
wget https://github.com/AppImage/AppImageKit/releases/download/13/appimagetool-x86_64.AppImage

# Make it executable and move it to your local bin path
chmod +x appimagetool-x86_64.AppImage
sudo mv appimagetool-x86_64.AppImage /usr/local/bin/appimagetool

Step 2: Create the AppDir Structure

An AppImage is simply a mounted filesystem image containing an organized folder called an AppDir.

Navigate to your workspace and create the following directory structure:

Bash

mkdir -p Calculator.AppDir/usr/bin
mkdir -p Calculator.AppDir/usr/share/icons/hicolor/256x256/apps

Now, place your code inside the application directory:

Bash

# Copy your Python script to the AppDir and make it executable
cp /home/mhcrnl/Desktop/Iulie_2026/Python-GUI-Project/calculator/calculator2.py Calculator.AppDir/usr/bin/calculator2.py
chmod +x Calculator.AppDir/usr/bin/calculator2.py

Step 3: Create Required Desktop Files

An AppImage requires three core items in the root of the AppDir:

AppRun (An executable script that launches the app)
calculator.desktop (The desktop integration file)
calculator.png (The application icon)

1. Create `Calculator.AppDir/AppRun`

This script tells the AppImage system how to start your Python program.

Bash

nano Calculator.AppDir/AppRun

Paste the following content:

Bash
#!/bin/sh
HERE="$(dirname "$(readlink -f "${0}")")"

# Execute your python script using the system's python interpreter
exec python3 "$HERE/usr/bin/calculator2.py" "$@"

Save and exit (Ctrl+O, Enter, Ctrl+X), then make it executable:

Bash

chmod +x Calculator.AppDir/AppRun

2. Create `Calculator.AppDir/calculator.desktop`

This file maps the shortcuts and metadata of your tool.

Bash

nano Calculator.AppDir/calculator.desktop

Paste the following content:

Ini, TOML
[Desktop Entry]
Type=Application
Name=Python Tkinter Calculator
Comment=An adaptive desktop calculator built in Python
Exec=calculator2.py
Icon=calculator
Categories=Utility;Calculator;
Terminal=false

3. Add an Icon

Place any .png icon image into the root folder as calculator.png (matching the Icon= value in your desktop file) and also in the icon theme subpath:

Bash

# Assuming you have an icon file named icon.png
cp icon.png Calculator.AppDir/calculator.png
cp icon.png Calculator.AppDir/usr/share/icons/hicolor/256x256/apps/calculator.png

(If you don't have an icon yet, you can download a placeholder square PNG image for testing purposes).

Step 4: Compile into an AppImage

Your Calculator.AppDir folder structure should look like this:

Plaintext

Calculator.AppDir/
├── AppRun
├── calculator.desktop
├── calculator.png
└── usr/
    ├── bin/
    │   └── calculator2.py
    └── share/
        └── icons/
            └── hicolor/
                └── ...

Run appimagetool pointing to your target folder:

Bash

appimagetool Calculator.AppDir

Step 5: Test Your New AppImage

The compilation tool will generate a single, standalone binary named something like Python_Tkinter_Calculator-x86_64.AppImage.

You can test running it right away:

Bash

./Python_Tkinter_Calculator-x86_64.AppImage

Alternative (Advanced Deployment via PyInstaller)

If you want your AppImage to run on computers that do not have Python or Tkinter installed, you should use PyInstaller inside the AppRun flow instead of trusting the host's standard native python3 path. You can bundle your script via PyInstaller first:

Bash

pip install pyinstaller
pyinstaller --onefile --windowed calculator2.py

Then, instead of putting the raw .py file into usr/bin/, you copy the compiled binary from dist/calculator2 into Calculator.AppDir/usr/bin/ and update your AppRun file to execute that executable binary instead.

Search This Blog

Linux Magazin