#4030·Nuitka

Linux AppImage build in GitHub CD fails with TypeError: payload_dir is None

Author: nerraderCreated Sep 9, 2026Updated Sep 11, 2026
Labelsbugfactoryexcellent_report

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

bash
python -m nuitka --version

NOTE: 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)

bash
python -m nuitka --list-distribution-metadata

Nuitka 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

bash
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: ignore

Yes 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_site

in build-linux.sh:

bash
#!/usr/bin/env bash
set -e

uv run nuitka \
  --mode=app \
  --linux-create-installer \
  --linux-app-icon=assets/wordee-icon.png \
  src/wordee/main.py

Expected 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/