Linux AppImage build in GitHub CD fails with TypeError: payload_dir is None
Bug Description
The linux AppImage build in my CD fails after encountering a TypeError where payload_dir is NoneType.
️ Environment
1. Nuitka Version, Python Version, OS, and Platform
python -m nuitka --versionNOTE: I ran uv run nuitka --version instead, don't know if that makes a difference but seems like the previous command could not find the module named Nuitka.
4.2.1
Update status: up to date with stable release '4.2.1' (cached, 2 days old).
Commercial: None
Python: 3.14.5 (tags/v3.14.5:5607950, May 10 2026, 10:43:50) [MSC v.1944 64 bit (AMD64)]
Flavor: CPython Official
GIL: yes
Executable: ~\coding\python\projects\wordle.venv\Scripts\python.exe
OS: Windows
Arch: x86_64
WindowsRelease: 11
Nuitka-Scons: Non downloaded winlibs-gcc
Nuitka-Scons: 'C:\Users\darre\AppData\Local\Microsoft\WinGet\Packages\BrechtSanders.WinLibs.POSIX.UCRT_Microsoft.Winget.
Source_8wekyb3d8bbwe\mingw64\bin\gcc.exe'
Nuitka-Scons: is being ignored, Nuitka is very dependent on the precise one.
Version C compiler: ~\AppData\Local\Nuitka\Nuitka\Cache\DOWNLO~1\pip\private-49c291cb\Lib\site-packages\ziglang\zig.exe (zig.exe 0.16.0).
2. How Nuitka and Python were Installed
i just know that i ran uv init or some uv commands to set up my project and it just worked, i dont really know exactly how i installed python.
Nuitka was installed using uv.
3. Relevant PyPI Packages and Versions
If specific packages are involved (e.g., numpy), list their names and versions. Shorten the output
of python -m pip list -v to only include relevant packages, but in doubt a longer list is not
necessarily harmful.
Package Version Editable project location
anyio 4.14.2 ast-serialize 0.6.0 certifi 2026.6.17 cfgv 3.5.0 colorama 0.4.6 distlib 0.4.3 filelock 3.32.2 h11 0.16.0 httpcore 1.0.9 httpx 0.28.1 identify 2.6.19 idna 3.18 iniconfig 2.3.0 librt 0.13.0 loguru 0.7.3 mypy 2.3.0 mypy-extensions 1.1.0 nodeenv 1.10.0 nuitka 4.2.1 packaging 26.2 pathspec 1.1.1 platformdirs 4.10.0 pluggy 1.6.0 pre-commit 4.6.1 pygments 2.20.0 pyside6 6.11.1 pyside6-addons 6.11.1 pyside6-essentials 6.11.1 pytest 9.1.1 pytest-mock 3.15.1 pytest-qt 4.5.0 python-discovery 1.5.1 pyyaml 6.0.3 respx 0.23.1 ruff 0.15.21 shiboken6 6.11.1 typing-extensions 4.16.0 virtualenv 21.7.3 win32-setctime 1.2.0 wordee 0.1.0 (mine)
python -m nuitka --list-distribution-metadataNuitka 4.2.1 uv PySide6 6.11.1 uv PySide6_Addons 6.11.1 uv PySide6_Essentials 6.11.1 uv PyYAML 6.0.3 uv Pygments 2.20.0 uv anyio 4.14.2 uv ast_serialize 0.6.0 uv certifi 2026.6.17 uv cfgv 3.5.0 uv colorama 0.4.6 uv distlib 0.4.3 uv filelock 3.32.2 uv h11 0.16.0 uv httpcore 1.0.9 uv httpx 0.28.1 uv identify 2.6.19 uv idna 3.18 uv iniconfig 2.3.0 uv librt 0.13.0 uv loguru 0.7.3 uv mypy 2.3.0 uv mypy_extensions 1.1.0 uv nodeenv 1.10.0 uv packaging 26.2 uv pathspec 1.1.1 uv platformdirs 4.10.0 uv pluggy 1.6.0 uv pre_commit 4.6.1 uv pytest 9.1.1 uv pytest-mock 3.15.1 uv pytest-qt 4.5.0 uv python-discovery 1.5.1 uv respx 0.23.1 uv ruff 0.15.21 uv shiboken6 6.11.1 uv typing_extensions 4.16.0 uv virtualenv 21.7.3 uv win32_setctime 1.2.0 uv wordee 0.1.0 uv
️ To Reproduce
1. "Hello World" Test (if applicable)
Python 3.13 and Python 3.14 Nuitka 4.2.1 Ubuntu GitHub Actions runner
The compilation successfully produces hello.bin, but when --linux-create-installer attempts to create the AppImage, Nuitka crashes with:
This error fails on both versions of Python.
This error also fails on the develop branch of Nuitka, also on both versions.
TypeError: stat: path should be string, bytes, os.PathLike or integer, not NoneType
The failure occurs during AppImage creation after appimagetool is downloaded.
2. Short, Self-Contained, Correct, Eligible (SSCCE) Example
name: Test Nuitka
on:
workflow_dispatch:
jobs:
build:
strategy:
fail-fast: false
matrix:
python-version: [3.13, 3.14]
nuitka-version:
- "nuitka"
- "nuitka @ git+https://github.com/Nuitka/Nuitka.git@develop"
runs-on: ubuntu-latest
steps:
- name: Install uv
uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
with:
enable-cache: true
- name: Install Python using UV
run: uv python install ${{matrix.python-version}}
# this needs to exist so AppImage can be executed
- name: Install Linux dependencies
if: runner.os == 'Linux'
run: |
sudo apt-get update
sudo apt-get install -y libfuse2 || sudo apt-get install -y libfuse2t64
- name: Create Hello World
run: |
echo 'print("hello world")' > hello.py
- name: Build AppImage
run: |
uv run \
--no-project \
--python ${{matrix.python-version}} \
--with "${{matrix.nuitka-version}}" \
nuitka \
--mode=app \
--linux-create-installer \
--product-name=HelloWorld \
--product-version=1.0.0 \
--company-name=test \
--assume-yes-for-downloads \
hello.py
- name: Upload crash report
if: always()
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
with:
name: nuitka-crash-report ${{matrix.python-version}} ${{matrix.nuitka-version}}
path: nuitka-crash-report.xml
if-no-files-found: ignoreYes it all fails with the same error on the develop branch and on each python version.
also note that the upload crash report does not work for the develop branch test cuz it has like git @+ random symbols so it doesnt work as a name this has nothing to do with nuitka but if a maintainer/contributor or something runs this .yaml code then jsut know that ye that error does exist
3. Nuitka Command Line Options
# nuitka-project: --enable-plugin=pyside6
# nuitka-project: --company-name=Nerrader
# nuitka-project: --product-name=WORDEE
# nuitka-project: --output-filename=WORDEE
# nuitka-project: --output-dir=dist
# nuitka-project: --product-version=0.1.0
# nuitka-project: --assume-yes-for-downloads
# nuitka-project: --no_docstrings
# nuitka-project: --no_sitein build-linux.sh:
#!/usr/bin/env bash
set -e
uv run nuitka \
--mode=app \
--linux-create-installer \
--linux-app-icon=assets/wordee-icon.png \
src/wordee/main.pyExpected Behavior
The AppImage to generate successfully and not generate a TypeError pointing at Nuitka's internals
Actual Behavior & Output
Generated this traceback:
##[debug]/usr/bin/bash -e /home/runner/work/_temp/edc2e92b-341f-4730-9d35-01cbd279a18a.sh
Nuitka-Options: Used command line options:
Nuitka-Options: --enable-plugin=pyside6 --company-name=Nerrader --product-name=WORDEE --output-filename=WORDEE --output-dir=dist --product-version=0.1.0 --assume-yes-for-downloads --mode=app --linux-create-installer --linux-app-icon=assets/wordee-icon.png src/wordee/main.py
Nuitka: Starting Python compilation with:
Nuitka: Version '4.2.1' on Python 3.14 (flavor 'Python Build Standalone') commercial grade 'not installed'.
Nuitka: Module(s) 'csv' necessitate pass 3
Nuitka-Plugins:pyside6: Including Qt plugins 'egldeviceintegrations,iconengines,imageformats,platforms,platformthemes,printsupport,tls,wayland-decoration-client,wayland-graphics-integration-client,wayland-shell-integration,xcbglintegrations' below 'PySide6/qt-plugins'.
Nuitka: Completed Python level compilation and optimization.
Nuitka: Generating source code for C backend compiler.
Nuitka: Running data composer tool for optimal constant value handling.
Nuitka: Running C compilation via Scons.
Nuitka-Scons: Backend C compiler: gcc (gcc 13).
Nuitka-Scons: Backend C linking with 174 files (no progress information available for this stage).
Nuitka-Scons:WARNING: You are not using ccache, re-compilation of identical code will be slower than necessary. Use your OS package manager to install it.
Nuitka-Plugins:data-files: Included data file 'certifi/cacert.pem' due to package data for 'certifi'.
Nuitka-Onefile: Creating single file from dist folder, this may take a while.
Nuitka-Onefile: Running bootstrap binary compilation via Scons.
Nuitka-Onefile: Using compression for onefile payload.
Nuitka-Onefile: Onefile payload compression ratio (27.28%) size 156371707 to 42664593.
Nuitka-Scons: Onefile C compiler: gcc (gcc 13).
Nuitka-Scons: Onefile C linking with 2 files (no progress information available for this stage).
Nuitka-Scons:WARNING: You are not using ccache, re-compilation of identical code will be slower than necessary. Use your OS package manager to install it.
Nuitka-Onefile: Keeping onefile build directory 'dist/main.onefile-build'.
Nuitka: Created desktop file 'dist/com.nerrader.wordee.desktop'.
Nuitka: Created AppStream metainfo file 'dist/com.nerrader.wordee.metainfo.xml'.
Nuitka: Keeping dist folder 'dist/main.dist' for inspection, no need to use it.
Nuitka: Keeping build directory 'dist/main.build'.
Nuitka: Successfully created 'dist/WORDEE'.
Nuitka: Downloading 'https://github.com/AppImage/AppImageKit/releases/download/continuous/appimagetool-x86_64.AppImage'.
Traceback (most recent call last):
File "/home/runner/work/wordee/wordee/.venv/lib/python3.14/site-packages/nuitka/__main__.py", line 325, in <module>
main()
~~~~^^
File "/home/runner/work/wordee/wordee/.venv/lib/python3.14/site-packages/nuitka/__main__.py", line 307, in main
nuitka_main()
~~~~~~~~~~~^^
File "/home/runner/work/wordee/wordee/.venv/lib/python3.14/site-packages/nuitka/MainControl.py", line 1456, in main
_main()
~~~~~^^
File "/home/runner/work/wordee/wordee/.venv/lib/python3.14/site-packages/nuitka/MainControl.py", line 1431, in _main
createInstallerDispatch()
~~~~~~~~~~~~~~~~~~~~~~~^^
File "/home/runner/work/wordee/wordee/.venv/lib/python3.14/site-packages/nuitka/installer/Installer.py", line 124, in createInstallerDispatch
createLinuxInstaller(
~~~~~~~~~~~~~~~~~~~~^
installer_tool_path=getLinuxInstallerAppImagetoolPath(),
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
)
^
File "/home/runner/work/wordee/wordee/.venv/lib/python3.14/site-packages/nuitka/installer/LinuxInstaller.py", line 103, in createLinuxInstaller
artifact_filename = createAppImage(
product_name=getProductName(),
...<8 lines>...
installer_tool_path=installer_tool_path,
)
File "/home/runner/work/wordee/wordee/.venv/lib/python3.14/site-packages/nuitka/installer/backends/AppImageBackend.py", line 207, in createAppImage
if not os.path.isdir(payload_dir):
~~~~~~~~~~~~~^^^^^^^^^^^^^
File "/home/runner/work/_temp/uv-python-dir/cpython-3.14.7-linux-x86_64-gnu/lib/python3.14/genericpath.py", line 51, in isdir
st = os.stat(s)
TypeError: stat: path should be string, bytes, os.PathLike or integer, not NoneType
Nuitka-Reports: Compilation crash report written to file 'nuitka-crash-report.xml'. Please include it in your bug report.
Error: Process completed with exit code 1.↩️ Regression (if applicable)
I do not know if this AppImage building system worked in any other previous Nuitka version.
Additional Context (Optional)
I have no clue if this could possibly help, but I will send the .yaml file I used for the initial generation of the .AppImage in my project, not the test hello world one.
name: Release
on:
workflow_dispatch:
push:
tags:
- "v*"
permissions:
contents: write
jobs:
check-main:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
fetch-depth: 0
- name: Check tag is on main
run: |
git fetch origin main
# check if tag is in main branch
if ! git merge-base --is-ancestor "$GITHUB_SHA" "origin/main"; then
echo "ERROR: Release tag must point to a commit on main."
exit 1
fi
build:
needs: check-main
strategy:
fail-fast: false
matrix:
include:
- os: ubuntu-latest
name: linux
build: bash scripts/build-linux.sh
- os: macos-latest
build: bash scripts/build-macos.sh
name: macos
- os: windows-latest
name: windows
build: pwsh scripts/build-windows.ps1
runs-on: ${{ matrix.os }}
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- name: Install uv
uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
with:
enable-cache: true
- name: Install Python using UV
run: uv python install
- name: Get dependencies
run: uv sync --locked
# this needs to exist so AppImage can be executed
- name: Install Linux dependencies
if: runner.os == 'Linux'
run: |
sudo apt-get update
sudo apt-get install -y libfuse2 || sudo apt-get install -y libfuse2t64
- name: Build ${{ matrix.name }}
run: |
${{ matrix.build }}
- name: Upload build
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
with:
name: ${{ matrix.name }}
path: dist/Source: Nuitka/Nuitka