⚙️ Nuitka – Guide complet du compilateur Python

Cas adaptés à IDEO-Lab

Décision rapide

                                Is it business-critical?
                                │
                                ├── No
                                │   └── Keep as normal Python
                                │
                                └── Yes
                                │
                                ├── Is it isolated?
                                │   ├── Yes
                                │   │   └── Compile with Nuitka
                                │   │
                                │   └── No
                                │       └── Refactor into a small engine first
                                │
                                └── Does it need Django runtime?
                                ├── No
                                │   └── Better candidate
                                └── Yes
                                └── Compile carefully, test deeply
                            

Niveaux de protection

Architecture de protection recommandée

                                public_package/
                                │
                                ├── admin.py
                                ├── apps.py
                                ├── views.py
                                ├── templates/
                                ├── static/
                                │
                                ├── public_api.py
                                │   └── imports compiled engine
                                │
                                └── private_core/
                                ├── engine_compiled.pyd / .so
                                ├── license_check.pyd / .so
                                └── rules_compiled.pyd / .so
                            

Approche recommandée pour un addon Django

                                ideolab_admin_tools/
                                │
                                ├── __init__.py
                                ├── apps.py
                                ├── admin.py
                                ├── urls.py
                                ├── views.py
                                ├── templates/
                                ├── static/
                                │
                                ├── public_api.py
                                │
                                └── private_core/
                                ├── __init__.py
                                ├── admin_scanner.py
                                ├── model_introspection.py
                                ├── scoring.py
                                ├── report_builder.py
                                └── license_rules.py
                            

Ici, admin.py, views.py et les templates restent classiques. Le dossier private_core peut être progressivement compilé.

Ce qu'il faut éviter au début

Checklist avant compilation

• Le module est stable.
• Le module a des tests unitaires.
• Les imports sont explicites.
• Les fichiers data sont identifiés.
• Les dépendances natives sont connues.
• Le module peut être testé hors interface web.
• Le build est documenté dans un script.

Checklist après compilation

• Le binaire ou module s'exécute.
• Les logs sont lisibles.
• Les erreurs sont capturées proprement.
• Les tests métier passent.
• Le livrable fonctionne hors environnement dev.
• La taille du package est acceptable.
• La procédure de rebuild est claire.

Commandes de départ

                                python -m pip install -U nuitka ordered-set zstandard

                                python -m nuitka --version

                                python -m nuitka app.py

                                python -m nuitka --standalone app.py

                                python -m nuitka --standalone --onefile app.py
                            

Mini-conclusion

Pipeline mental de validation

                                CPython OK ?
                                │
                                ├── Non
                                │   └── Corriger le code Python avant Nuitka
                                │
                                └── Oui
                                │
                                ▼
                                Build Nuitka OK ?
                                │
                                ├── Non
                                │   ├── Vérifier compilateur
                                │   ├── Vérifier imports
                                │   └── Vérifier plugins
                                │
                                └── Oui
                                │
                                ▼
                                Runtime OK dans .dist ?
                                │
                                ├── Non
                                │   ├── Fichier data manquant
                                │   ├── DLL manquante
                                │   └── Chemin relatif incorrect
                                │
                                └── Oui
                                │
                                ▼
                                Onefile possible
                            

Messages à surveiller

• Warning d'import : souvent lié à un import dynamique ou optionnel.
• Warning plugin : indique qu'un package a besoin d'un traitement spécifique.
• Erreur compilateur : toolchain absente, mal configurée ou incompatible.
• Erreur de link : symbole ou librairie native introuvable.
• Erreur runtime : dépendance présente au build mais absente au lancement.

Graphe d'imports simple

                                app.py
                                │
                                ├── import core.engine
                                │   ├── import core.rules
                                │   ├── import core.scoring
                                │   └── import core.formatters
                                │
                                ├── import click
                                └── import pathlib

                                Nuitka peut suivre ce graphe facilement.
                            

Import dynamique plus risqué

                                plugin_name = settings.SELECTED_PLUGIN

                                module = importlib.import_module(plugin_name)

                                module.run()

                                Nuitka ne peut pas toujours deviner
                                la valeur réelle de plugin_name.
                            

Commandes universelles

                                # Créer un environnement virtuel local
                                python -m venv .venv

                                # Windows CMD
                                .venv\Scripts\activate.bat

                                # Windows PowerShell
                                .venv\Scripts\Activate.ps1

                                # Linux / macOS
                                source .venv/bin/activate

                                # Vérifier que le venv est actif
                                python -c "import sys; print(sys.executable)"
                            

Installer Nuitka proprement

                                # Mettre à jour les outils de packaging Python
                                python -m pip install --upgrade pip setuptools wheel

                                # Installer Nuitka et dépendances recommandées
                                python -m pip install -U nuitka ordered-set zstandard

                                # Vérifier
                                python -m nuitka --version
                                python -m pip show nuitka
                            

Arborescence recommandée

                                nuitka_lab/
                                │
                                ├── .venv/
                                ├── hello.py
                                ├── requirements-build.txt
                                ├── build/
                                │   ├── logs/
                                │   └── dist/
                                └── README_BUILD.md
                            

À ne pas faire

• Installer Nuitka globalement sans savoir quel Python est utilisé.
• Mélanger plusieurs versions de Python dans le même terminal.
• Compiler depuis un dossier contenant des caractères bizarres ou chemins très longs.
• Compiler un gros projet sans test minimal préalable.
• Oublier de vérifier sys.executable.

Plan Windows recommandé

                                Windows
                                │
                                ├── Installer Python 64-bit
                                │   ├── Add Python to PATH
                                │   └── Vérifier python --version
                                │
                                ├── Installer Visual Studio Build Tools
                                │   └── Desktop development with C++
                                │
                                ├── Créer .venv
                                │   └── python -m venv .venv
                                │
                                ├── Installer Nuitka
                                │   └── pip install -U nuitka ordered-set zstandard
                                │
                                └── Compiler hello.py
                                └── python -m nuitka hello.py
                            

Commandes Windows

                                # Vérifier Python
                                python --version
                                python -c "import sys; print(sys.version); print(sys.executable)"

                                # Créer et activer le venv
                                python -m venv .venv

                                # CMD
                                .venv\Scripts\activate.bat

                                # PowerShell
                                .venv\Scripts\Activate.ps1

                                # Mettre pip à jour
                                python -m pip install --upgrade pip setuptools wheel

                                # Installer Nuitka
                                python -m pip install -U nuitka ordered-set zstandard

                                # Vérifier Nuitka
                                python -m nuitka --version
                            

Installation système

                                sudo apt update

                                sudo apt install -y \
                                python3 \
                                python3-venv \
                                python3-pip \
                                build-essential \
                                ccache \
                                patchelf
                            

build-essential installe notamment gcc, g++ et make. patchelf aide sur certains builds standalone Linux. ccache peut accélérer les recompilations.

Créer le venv et installer Nuitka

                                mkdir -p ~/nuitka_lab
                                cd ~/nuitka_lab

                                python3 -m venv .venv
                                source .venv/bin/activate

                                python -m pip install --upgrade pip setuptools wheel
                                python -m pip install -U nuitka ordered-set zstandard

                                python -m nuitka --version
                            

ccache sous Linux

                                sudo apt install -y ccache

                                ccache --version
                                ccache --show-stats

                                # Optionnel : voir le chemin
                                which ccache
                            

ccache mémorise certains résultats de compilation. Si les fichiers générés n'ont pas changé, les recompilations peuvent être accélérées.

Dossier de build propre

                                build/
                                │
                                ├── nuitka/
                                │   ├── hello.build/
                                │   ├── hello.dist/
                                │   └── hello.onefile-build/
                                │
                                ├── logs/
                                │   ├── build_hello.log
                                │   └── runtime_hello.log
                                │
                                └── reports/
                                ├── environment.txt
                                └── command_used.txt
                            

Checks Python / pip / Nuitka

                                python -c "import sys; print(sys.version); print(sys.executable)"
                                python -m pip --version
                                python -m pip list

                                python -m nuitka --version
                                python -m nuitka --help
                            

Checks système

                                # Linux
                                which python
                                which gcc
                                gcc --version
                                g++ --version
                                patchelf --version

                                # Windows
                                where python
                                where pip
                                python --version
                                python -m nuitka --version
                            

Créer le fichier de test

                                # Linux / macOS
                                cat > hello.py <<'PY'
                                import sys
                                import platform

                                print("hello from nuitka")
                                print("python:", sys.version)
                                print("executable:", sys.executable)
                                print("platform:", platform.platform())
                                PY
                            

                                # Windows PowerShell
                                @'
                                import sys
                                import platform

                                print("hello from nuitka")
                                print("python:", sys.version)
                                print("executable:", sys.executable)
                                print("platform:", platform.platform())
                                '@ | Set-Content -Encoding UTF8 hello.py
                            

Exécuter en Python pur

                                python hello.py
                            

Cette étape valide que le script fonctionne avant toute compilation. Si cette commande échoue, le problème n'est pas Nuitka.

Compiler en mode simple

                                python -m nuitka hello.py
                            

Standalone recommandé

                                python -m nuitka \
                                --standalone \
                                --output-dir=build/nuitka \
                                hello.py

                                # Linux
                                ./build/nuitka/hello.dist/hello

                                # Windows
                                build\nuitka\hello.dist\hello.exe
                            

Onefile après validation

                                python -m nuitka \
                                --standalone \
                                --onefile \
                                --output-dir=build/nuitka \
                                hello.py

                                # Linux
                                ./build/nuitka/hello.bin

                                # Windows
                                build\nuitka\hello.exe
                            

Diagnostic rapide

                                Erreur installation ?
                                │
                                ├── Python introuvable
                                │   └── PATH / installation Python
                                │
                                ├── Nuitka introuvable
                                │   └── pip install dans le bon venv
                                │
                                ├── Compilateur introuvable
                                │   ├── Windows : Build Tools
                                │   └── Linux   : build-essential
                                │
                                ├── Build échoue
                                │   └── Lire logs Nuitka
                                │
                                └── Runtime échoue
                                ├── Tester standalone
                                ├── Vérifier data files
                                └── Vérifier DLL / SO
                            

Commande de rapport environnement

                                python - <<'PY'
                                import sys
                                import platform
                                import subprocess

                                print("Python:", sys.version)
                                print("Executable:", sys.executable)
                                print("Platform:", platform.platform())
                                print("Machine:", platform.machine())

                                try:
                                import nuitka
                                print("Nuitka import: OK")
                                except Exception as exc:
                                print("Nuitka import: KO", exc)

                                subprocess.run([sys.executable, "-m", "pip", "--version"])
                                PY
                            

Fichier requirements-build.txt

                                # requirements-build.txt
                                nuitka
                                ordered-set
                                zstandard
                                wheel
                                setuptools
                                pytest
                            

Installation reproductible

                                python -m venv .venv
                                source .venv/bin/activate

                                python -m pip install --upgrade pip setuptools wheel
                                python -m pip install -r requirements-build.txt

                                python -m nuitka --version
                            

Script build recommandé

                                scripts/
                                │
                                ├── build_nuitka_module.py
                                ├── build_nuitka_cli.py
                                ├── check_nuitka_env.py
                                └── clean_nuitka_build.py

                                build/
                                │
                                ├── nuitka/
                                ├── logs/
                                └── reports/
                            

Code Python complet

from __future__ import annotations

                                import platform
                                import sys
                                from datetime import datetime
                                from pathlib import Path


                                def compute_score(values: list[int]) -> int:
                                """
                                Small deterministic function used to verify that the compiled binary
                                returns the same business result as the Python source version.
                                """
                                return sum(value * 3 for value in values) + 17


                                def describe_runtime() -> dict[str, str]:
                                """
                                Return runtime information that helps compare CPython execution
                                and Nuitka compiled execution.
                                """
                                return {
                                "python": sys.version.split()[0],
                                "platform": f"{platform.system()} {platform.machine()}",
                                "executable": str(Path(sys.executable).name),
                                "cwd": str(Path.cwd()),
                                }


                                def main() -> int:
                                runtime = describe_runtime()
                                score = compute_score([1, 2, 3, 4])

                                print("Nuitka smoke test")
                                print(f"Python: {runtime['python']}")
                                print(f"Platform: {runtime['platform']}")
                                print(f"Executable: {runtime['executable']}")
                                print(f"Working directory: {runtime['cwd']}")
                                print(f"Time: {datetime.now().isoformat(timespec='seconds')}")
                                print(f"Score: {score}")

                                if score != 47:
                                print("Unexpected score")
                                return 2

                                return 0


                                if __name__ == "__main__":
                                raise SystemExit(main())

Créer le fichier rapidement

Linux / macOS

cat > hello_nuitka.py <<'PY'
                                from __future__ import annotations

                                import platform
                                import sys
                                from datetime import datetime
                                from pathlib import Path


                                def compute_score(values: list[int]) -> int:
                                return sum(value * 3 for value in values) + 17


                                def describe_runtime() -> dict[str, str]:
                                return {
                                "python": sys.version.split()[0],
                                "platform": f"{platform.system()} {platform.machine()}",
                                "executable": str(Path(sys.executable).name),
                                "cwd": str(Path.cwd()),
                                }


                                def main() -> int:
                                runtime = describe_runtime()
                                score = compute_score([1, 2, 3, 4])

                                print("Nuitka smoke test")
                                print(f"Python: {runtime['python']}")
                                print(f"Platform: {runtime['platform']}")
                                print(f"Executable: {runtime['executable']}")
                                print(f"Working directory: {runtime['cwd']}")
                                print(f"Time: {datetime.now().isoformat(timespec='seconds')}")
                                print(f"Score: {score}")

                                if score != 47:
                                print("Unexpected score")
                                return 2

                                return 0


                                if __name__ == "__main__":
                                raise SystemExit(main())
                                PY

Windows PowerShell

@'
                                from __future__ import annotations

                                import platform
                                import sys
                                from datetime import datetime
                                from pathlib import Path


                                def compute_score(values: list[int]) -> int:
                                return sum(value * 3 for value in values) + 17


                                def describe_runtime() -> dict[str, str]:
                                return {
                                "python": sys.version.split()[0],
                                "platform": f"{platform.system()} {platform.machine()}",
                                "executable": str(Path(sys.executable).name),
                                "cwd": str(Path.cwd()),
                                }


                                def main() -> int:
                                runtime = describe_runtime()
                                score = compute_score([1, 2, 3, 4])

                                print("Nuitka smoke test")
                                print(f"Python: {runtime['python']}")
                                print(f"Platform: {runtime['platform']}")
                                print(f"Executable: {runtime['executable']}")
                                print(f"Working directory: {runtime['cwd']}")
                                print(f"Time: {datetime.now().isoformat(timespec='seconds')}")
                                print(f"Score: {score}")

                                if score != 47:
                                print("Unexpected score")
                                return 2

                                return 0


                                if __name__ == "__main__":
                                raise SystemExit(main())
                                '@ | Set-Content -Encoding UTF8 hello_nuitka.py

Commande

python hello_nuitka.py

Sortie attendue

Nuitka smoke test
                                Python: 3.12.x
                                Platform: Windows AMD64
                                Executable: python.exe
                                Working directory: C:\dev\nuitka_quickstart
                                Time: 2026-04-26T12:34:56
                                Score: 47

Contrôles

Vérifier le code retour

# Linux / macOS
                                echo $?

                                # Windows CMD
                                echo %ERRORLEVEL%

                                # Windows PowerShell
                                $LASTEXITCODE

Commande simple

python -m nuitka hello_nuitka.py

Commande avec dossier de sortie

python -m nuitka \
                                --output-dir=build/nuitka \
                                hello_nuitka.py

Variante avec logs

# Linux / macOS
                                python -m nuitka --output-dir=build/nuitka hello_nuitka.py \
                                2>&1 | tee build/logs/quickstart_accelerated.log

Ce que ce mode produit

Commande standalone

python -m nuitka \
                                --standalone \
                                --assume-yes-for-downloads \
                                --output-dir=build/nuitka \
                                hello_nuitka.py

Exécution

# Windows
                                build\nuitka\hello_nuitka.dist\hello_nuitka.exe

                                # Linux / macOS
                                ./build/nuitka/hello_nuitka.dist/hello_nuitka

Anatomie du standalone

                                hello_nuitka.dist/
                                │
                                ├── hello_nuitka.exe / hello_nuitka
                                ├── python runtime components
                                ├── standard library pieces
                                ├── extension modules
                                ├── native libraries
                                └── support files
                            

Commande onefile

python -m nuitka \
                                --standalone \
                                --onefile \
                                --assume-yes-for-downloads \
                                --output-dir=build/nuitka \
                                hello_nuitka.py

Exécution

# Windows
                                build\nuitka\hello_nuitka.exe

                                # Linux / macOS
                                ./build/nuitka/hello_nuitka.bin
                                # ou selon la sortie :
                                ./build/nuitka/hello_nuitka

Cycle de vie d'un onefile

                                onefile executable
                                │
                                ├── Start
                                ├── Prepare temporary extraction area
                                ├── Extract embedded payload
                                ├── Launch compiled application
                                ├── Run program
                                └── Cleanup depending on runtime behavior
                            

Commandes de comparaison

# 1. Source
                                python hello_nuitka.py

                                # 2. Accelerated
                                # Windows
                                hello_nuitka.exe
                                # Linux / macOS
                                ./hello_nuitka

                                # 3. Standalone
                                # Windows
                                build\nuitka\hello_nuitka.dist\hello_nuitka.exe
                                # Linux / macOS
                                ./build/nuitka/hello_nuitka.dist/hello_nuitka

                                # 4. Onefile
                                # Windows
                                build\nuitka\hello_nuitka.exe
                                # Linux / macOS
                                ./build/nuitka/hello_nuitka.bin

Ce qui doit être identique

Structure après plusieurs builds

                                nuitka_quickstart/
                                │
                                ├── hello_nuitka.py
                                │
                                ├── hello_nuitka.build/
                                │   └── fichiers intermédiaires C/C++
                                │
                                ├── hello_nuitka.exe / hello_nuitka
                                │   └── build simple / accelerated
                                │
                                ├── build/
                                │   └── nuitka/
                                │       ├── hello_nuitka.build/
                                │       ├── hello_nuitka.dist/
                                │       │   ├── hello_nuitka.exe
                                │       │   └── dépendances runtime
                                │       │
                                │       └── hello_nuitka.exe / hello_nuitka.bin
                                │           └── onefile
                                │
                                └── build/logs/
                                ├── source.out
                                ├── standalone.out
                                └── quickstart_build.log
                            

Rôle des artefacts

Progression recommandée

                                hello_nuitka.py
                                │
                                └── OK
                                │
                                ▼
                                small_engine.py
                                │
                                └── OK
                                │
                                ▼
                                private_core/scoring.py
                                │
                                └── OK
                                │
                                ▼
                                private_core/analyzer.py
                                │
                                └── OK
                                │
                                ▼
                                integration with Django addon
                            

Critères pour choisir le premier vrai module

Commande

# Syntaxe moderne
                                python -m nuitka --mode=accelerated hello_nuitka.py

                                # Équivalent courant
                                python -m nuitka hello_nuitka.py

                                # Avec dossier de sortie propre
                                python -m nuitka \
                                --mode=accelerated \
                                --output-dir=build/nuitka \
                                hello_nuitka.py

Flux de build

                                hello_nuitka.py
                                │
                                ▼
                                Nuitka frontend
                                │
                                ▼
                                C/C++ generated files
                                │
                                ▼
                                Native compiler
                                │
                                ▼
                                Local executable
                            

Quand l'utiliser ?

Commande

# Syntaxe moderne
                                python -m nuitka \
                                --mode=standalone \
                                --assume-yes-for-downloads \
                                --output-dir=build/nuitka \
                                hello_nuitka.py

                                # Syntaxe équivalente courante
                                python -m nuitka \
                                --standalone \
                                --assume-yes-for-downloads \
                                --output-dir=build/nuitka \
                                hello_nuitka.py

Exécution

# Windows
                                build\nuitka\hello_nuitka.dist\hello_nuitka.exe

                                # Linux / macOS
                                ./build/nuitka/hello_nuitka.dist/hello_nuitka

Structure produite

                                hello_nuitka.dist/
                                │
                                ├── hello_nuitka.exe / hello_nuitka
                                ├── python runtime components
                                ├── standard library fragments
                                ├── compiled extension modules
                                ├── native DLL / SO / DYLIB
                                ├── package dependencies
                                └── included data files
                            

Commande

# Syntaxe moderne
                                python -m nuitka \
                                --mode=onefile \
                                --assume-yes-for-downloads \
                                --output-dir=build/nuitka \
                                hello_nuitka.py

                                # Syntaxe équivalente courante
                                python -m nuitka \
                                --standalone \
                                --onefile \
                                --assume-yes-for-downloads \
                                --output-dir=build/nuitka \
                                hello_nuitka.py

Exécution

# Windows
                                build\nuitka\hello_nuitka.exe

                                # Linux / macOS
                                ./build/nuitka/hello_nuitka.bin
                                # ou selon la sortie :
                                ./build/nuitka/hello_nuitka

Cycle de vie onefile

                                onefile executable
                                │
                                ├── Start executable
                                ├── Prepare temporary area
                                ├── Extract internal payload
                                ├── Launch compiled program
                                ├── Run application
                                └── Cleanup / exit
                            

Exemple simple

# core_engine.py contient le cœur propriétaire
                                python -m nuitka \
                                --mode=module \
                                --output-dir=build/nuitka \
                                core_engine.py

                                # Syntaxe équivalente
                                python -m nuitka \
                                --module \
                                --output-dir=build/nuitka \
                                core_engine.py

Résultats typiques

# Windows
                                core_engine.cp312-win_amd64.pyd

                                # Linux
                                core_engine.cpython-312-x86_64-linux-gnu.so

                                # macOS
                                core_engine.cpython-312-darwin.so

Architecture recommandée

                                my_addon/
                                │
                                ├── admin.py
                                ├── views.py
                                ├── apps.py
                                ├── templates/
                                │
                                ├── public_api.py
                                │   └── imports protected core
                                │
                                └── private_core/
                                ├── scoring.py          -> compiled
                                ├── analyzer.py         -> compiled
                                ├── rules.py            -> compiled
                                └── report_builder.py   -> compiled
                            

Structure exemple

                                private_core/
                                │
                                ├── __init__.py
                                ├── scoring.py
                                ├── analyzer.py
                                ├── rules.py
                                ├── report_builder.py
                                └── resources/
                                └── default_rules.json
                            

Commande indicative

python -m nuitka \
                                --mode=module \
                                --include-package=private_core \
                                --output-dir=build/nuitka \
                                private_core

Quand compiler un package ?

Architecture recommandée

                                ideolab_admin_tools/
                                │
                                ├── apps.py              -> Python classique
                                ├── admin.py             -> Python classique
                                ├── views.py             -> Python classique
                                ├── urls.py              -> Python classique
                                ├── templates/           -> fichiers data / HTML
                                ├── static/              -> fichiers data / assets
                                │
                                ├── public_api.py        -> façade claire
                                │
                                └── private_core/
                                ├── scoring.py       -> module compilé
                                ├── inspector.py     -> module compilé
                                ├── analyzer.py      -> module compilé
                                └── rules.py         -> module compilé
                            

Matrice Django

Commandes essentielles

# 1. Build simple / accelerated
                                python -m nuitka app.py

                                # 2. Standalone
                                python -m nuitka \
                                --mode=standalone \
                                --assume-yes-for-downloads \
                                --output-dir=build/nuitka \
                                app.py

                                # 3. Onefile
                                python -m nuitka \
                                --mode=onefile \
                                --assume-yes-for-downloads \
                                --output-dir=build/nuitka \
                                app.py

                                # 4. Module compilé
                                python -m nuitka \
                                --mode=module \
                                --output-dir=build/nuitka \
                                core_engine.py

                                # 5. Package / dépendances explicites
                                python -m nuitka \
                                --mode=module \
                                --include-package=private_core \
                                --output-dir=build/nuitka \
                                private_core

Résumé ultra-court

Imports explicites vs dynamiques

                                Import explicite
                                │
                                ├── import package.module
                                └── from package import module

                                Nuitka peut suivre facilement.
                                │
                                ▼
                                Import dynamique
                                │
                                ├── importlib.import_module(name)
                                ├── __import__(name)
                                ├── plugin registry
                                └── string path in settings

                                Nuitka peut avoir besoin d'une option.
                            

Options principales

Inclure un module dynamique

python -m nuitka \
                                --mode=standalone \
                                --include-module=myapp.plugins.csv_exporter \
                                app.py

Inclure un package complet

python -m nuitka \
                                --mode=standalone \
                                --include-package=myapp.plugins \
                                app.py

Exclure un package lourd inutile

python -m nuitka \
                                --mode=standalone \
                                --nofollow-import-to=tests \
                                --nofollow-import-to=matplotlib \
                                app.py

Cas plugin registry

# Code Python
                                plugin = importlib.import_module(settings.EXPORT_PLUGIN)

                                # Build
                                python -m nuitka \
                                --include-module=myapp.exporters.pdf \
                                --include-module=myapp.exporters.csv \
                                app.py

Carte des fichiers data

                                Application runtime
                                │
                                ├── Python code
                                │   └── compiled by Nuitka
                                │
                                └── Data files
                                ├── templates/*.html
                                ├── static/css/*.css
                                ├── static/js/*.js
                                ├── rules/*.json
                                ├── config/*.yaml
                                ├── certificates/*.pem
                                ├── sql/*.sql
                                └── assets/images/*
                            

Options principales

Inclure un fichier YAML

python -m nuitka \
                                --mode=standalone \
                                --include-data-files=config/default.yaml=config/default.yaml \
                                app.py

Inclure un dossier de règles

python -m nuitka \
                                --mode=standalone \
                                --include-data-dir=rules=rules \
                                app.py

Inclure templates et static

python -m nuitka \
                                --mode=standalone \
                                --include-data-dir=templates=templates \
                                --include-data-dir=static=static \
                                app.py

Exclure des fichiers inutiles

python -m nuitka \
                                --mode=standalone \
                                --include-data-dir=resources=resources \
                                --noinclude-data-files=resources/dev_only/* \
                                app.py

Principe

                                Package complex
                                │
                                ├── imports dynamiques
                                ├── data files
                                ├── DLL / SO
                                ├── backend runtime
                                └── discovery logic
                                │
                                ▼
                                Nuitka plugin
                                │
                                ├── knows special rules
                                ├── includes needed files
                                ├── handles dependencies
                                └── reduces manual options
                            

Options plugins

# Lister les plugins disponibles
                                python -m nuitka --plugin-list

                                # Exemple : activer un plugin
                                python -m nuitka \
                                --mode=standalone \
                                --enable-plugin=tk-inter \
                                app.py

Options utiles

Structure de build pro

                                build/
                                │
                                ├── nuitka/
                                │   ├── app.build/
                                │   ├── app.dist/
                                │   └── app.onefile-build/
                                │
                                ├── logs/
                                │   ├── build.log
                                │   ├── runtime.log
                                │   └── smoke_test.log
                                │
                                └── reports/
                                ├── compilation-report.xml
                                ├── environment.txt
                                └── command.txt
                            

Linux / macOS

mkdir -p build/logs build/reports

                                python -m nuitka \
                                --mode=standalone \
                                --output-dir=build/nuitka \
                                --report=build/reports/compilation-report.xml \
                                --show-progress \
                                app.py \
                                2>&1 | tee build/logs/build.log

Windows PowerShell

New-Item -ItemType Directory -Force build\logs, build\reports

                                python -m nuitka `
                                --mode=standalone `
                                --output-dir=build\nuitka `
                                --report=build\reports\compilation-report.xml `
                                --show-progress `
                                app.py *>&1 | Tee-Object build\logs\build.log

Ce qu'il faut compiler

                                Good target for protection
                                │
                                ├── private_core/scoring.py
                                ├── private_core/analyzer.py
                                ├── private_core/rules_engine.py
                                ├── private_core/parser.py
                                └── private_core/report_builder.py

                                Poor target at first
                                │
                                ├── tests/
                                ├── migrations/
                                ├── templates/
                                ├── admin.py glue code
                                └── unstable experimental files
                            

Options utiles indirectement

Architecture cible

                                ideolab_admin_tools/
                                │
                                ├── admin.py              -> Python lisible
                                ├── apps.py               -> Python lisible
                                ├── views.py              -> Python lisible
                                ├── templates/            -> data files
                                ├── static/               -> data files
                                │
                                ├── public_api.py         -> façade
                                │
                                └── private_core/
                                ├── scoring.py        -> compile module
                                ├── inspector.py      -> compile module
                                ├── analyzer.py       -> compile module
                                └── rules.json        -> include data
                            

Commande module pour cœur métier

python -m nuitka \
                                --mode=module \
                                --output-dir=build/nuitka \
                                --remove-output \
                                --show-progress \
                                ideolab_admin_tools/private_core/scoring.py

Commande standalone pour CLI d'analyse

python -m nuitka \
                                --mode=standalone \
                                --output-dir=build/nuitka \
                                --include-data-dir=ideolab_admin_tools/templates=ideolab_admin_tools/templates \
                                --include-data-dir=ideolab_admin_tools/static=ideolab_admin_tools/static \
                                tools/admin_scan_cli.py

Build standalone propre

python -m nuitka \
                                --mode=standalone \
                                --output-dir=build/nuitka \
                                --remove-output \
                                --jobs=8 \
                                --show-progress \
                                --show-memory \
                                --report=build/reports/compilation-report.xml \
                                --assume-yes-for-downloads \
                                hello_nuitka.py

Build onefile propre

python -m nuitka \
                                --mode=onefile \
                                --output-dir=build/nuitka \
                                --remove-output \
                                --jobs=8 \
                                --show-progress \
                                --report=build/reports/onefile-report.xml \
                                --assume-yes-for-downloads \
                                hello_nuitka.py

Build module protégé

python -m nuitka \
                                --mode=module \
                                --output-dir=build/nuitka \
                                --remove-output \
                                --show-progress \
                                --report=build/reports/module-report.xml \
                                private_core/scoring.py

Build avec data files

python -m nuitka \
                                --mode=standalone \
                                --output-dir=build/nuitka \
                                --include-data-dir=templates=templates \
                                --include-data-dir=static=static \
                                --include-data-files=config/default.yaml=config/default.yaml \
                                --include-data-files=rules/*.json=rules/ \
                                --report=build/reports/data-report.xml \
                                app.py

Commandes source

# Exécution directe
                                python hello_nuitka.py

                                # Vérifier le code retour Linux / macOS
                                echo $?

                                # Vérifier le code retour Windows CMD
                                echo %ERRORLEVEL%

                                # Vérifier le code retour Windows PowerShell
                                $LASTEXITCODE

                                # Vérification syntaxe sur un dossier
                                python -m compileall .

Contrôles attendus

Commande de build traçable

mkdir -p build/logs build/reports build/nuitka

                                python -m nuitka \
                                --mode=standalone \
                                --output-dir=build/nuitka \
                                --remove-output \
                                --show-progress \
                                --report=build/reports/compilation-report.xml \
                                --assume-yes-for-downloads \
                                hello_nuitka.py \
                                2>&1 | tee build/logs/build.log

Contrôles build

Commandes d'exécution

# Source
                                python hello_nuitka.py

                                # Standalone Windows
                                build\nuitka\hello_nuitka.dist\hello_nuitka.exe

                                # Standalone Linux / macOS
                                ./build/nuitka/hello_nuitka.dist/hello_nuitka

                                # Onefile Windows
                                build\nuitka\hello_nuitka.exe

                                # Onefile Linux / macOS
                                ./build/nuitka/hello_nuitka.bin

Ce qu'il faut observer

Test pytest minimal

from __future__ import annotations

                                import subprocess
                                import sys
                                from pathlib import Path


                                def run_command(command: list[str]) -> subprocess.CompletedProcess[str]:
                                return subprocess.run(
                                command,
                                text=True,
                                capture_output=True,
                                check=False,
                                )


                                def test_source_hello_nuitka():
                                result = run_command([sys.executable, "hello_nuitka.py"])

                                assert result.returncode == 0
                                assert "Nuitka smoke test" in result.stdout
                                assert "Score: 47" in result.stdout
                                assert result.stderr == ""


                                def test_compiled_binary_hello_nuitka():
                                if sys.platform == "win32":
                                binary = Path("build/nuitka/hello_nuitka.dist/hello_nuitka.exe")
                                else:
                                binary = Path("build/nuitka/hello_nuitka.dist/hello_nuitka")

                                assert binary.exists(), f"Missing binary: {binary}"

                                result = run_command([str(binary)])

                                assert result.returncode == 0
                                assert "Nuitka smoke test" in result.stdout
                                assert "Score: 47" in result.stdout

Organisation recommandée

tests/
                                │
                                ├── test_source_behavior.py
                                ├── test_binary_behavior.py
                                ├── test_packaging.py
                                └── test_performance_baseline.py

                                build/
                                │
                                ├── nuitka/
                                ├── logs/
                                └── reports/

Commandes

# Installer pytest si nécessaire
                                python -m pip install pytest

                                # Lancer tous les tests
                                python -m pytest -v

                                # Lancer seulement les tests binaires
                                python -m pytest -v tests/test_binary_behavior.py

Mesures simples

# Linux / macOS : temps détaillé
                                /usr/bin/time -v python hello_nuitka.py
                                /usr/bin/time -v ./build/nuitka/hello_nuitka.dist/hello_nuitka

                                # Windows PowerShell
                                Measure-Command { python .\hello_nuitka.py }
                                Measure-Command { .\build\nuitka\hello_nuitka.dist\hello_nuitka.exe }

Ce qu'il faut mesurer

Test hors dossier source

# Linux / macOS
                                mkdir -p /tmp/nuitka_runtime_test
                                cp -r build/nuitka/hello_nuitka.dist /tmp/nuitka_runtime_test/
                                cd /tmp/nuitka_runtime_test/hello_nuitka.dist
                                ./hello_nuitka

                                # Windows PowerShell
                                New-Item -ItemType Directory -Force C:\temp\nuitka_runtime_test
                                Copy-Item -Recurse build\nuitka\hello_nuitka.dist C:\temp\nuitka_runtime_test\
                                cd C:\temp\nuitka_runtime_test\hello_nuitka.dist
                                .\hello_nuitka.exe

Checklist packaging

Structure recommandée

build/reports/
                                │
                                ├── compilation-report.xml
                                ├── validation-report.md
                                ├── environment.txt
                                ├── command.txt
                                ├── source-output.txt
                                ├── binary-output.txt
                                ├── pytest-output.txt
                                └── performance-baseline.txt

Contenu minimum du rapport

Bon périmètre

Mauvais périmètre au début

Arborescence recommandée

ideolab_admin_tools/
                                │
                                ├── __init__.py
                                ├── apps.py
                                ├── admin.py
                                ├── urls.py
                                ├── views.py
                                │
                                ├── templates/
                                │   └── ideolab_admin_tools/
                                │       ├── dashboard.html
                                │       └── modal_detail.html
                                │
                                ├── static/
                                │   └── ideolab_admin_tools/
                                │       ├── css/
                                │       └── js/
                                │
                                ├── core_api.py
                                ├── normalizers.py
                                ├── dto.py
                                │
                                └── protected_core/
                                ├── __init__.py
                                ├── scoring.py              # source dev
                                ├── scoring_py.py           # fallback dev optionnel
                                ├── analyzer.py             # source dev
                                ├── analyzer_py.py          # fallback dev optionnel
                                ├── rules_engine.py         # source dev
                                ├── metadata_builder.py     # source dev
                                └── rules/
                                └── default_rules.json

Après compilation

ideolab_admin_tools/protected_core/
                                │
                                ├── __init__.py
                                │
                                ├── scoring.cp312-win_amd64.pyd
                                ├── analyzer.cp312-win_amd64.pyd
                                ├── rules_engine.cp312-win_amd64.pyd
                                ├── metadata_builder.cp312-win_amd64.pyd
                                │
                                ├── scoring_py.py        # seulement si fallback dev autorisé
                                ├── analyzer_py.py       # seulement si fallback dev autorisé
                                │
                                └── rules/
                                └── default_rules.json

Exemple core_api.py

from __future__ import annotations

                                import logging
                                import os
                                from typing import Any

                                logger = logging.getLogger(__name__)

                                ALLOW_PY_FALLBACK = os.environ.get("IDEOLAB_ADMIN_TOOLS_ALLOW_PY_FALLBACK") == "1"


                                def _load_scoring_engine():
                                try:
                                from .protected_core.scoring import compute_admin_score
                                return compute_admin_score
                                except Exception as exc:
                                logger.exception("Unable to import compiled scoring engine")

                                if not ALLOW_PY_FALLBACK:
                                raise RuntimeError(
                                "Compiled scoring engine is unavailable and Python fallback is disabled."
                                ) from exc

                                from .protected_core.scoring_py import compute_admin_score
                                logger.warning("Using Python fallback scoring engine")
                                return compute_admin_score


                                def score_model_admin(model_admin_class: type[Any]) -> dict[str, Any]:
                                """
                                Public stable API used by Django admin/views.

                                The Django layer should call this function and not the compiled module directly.
                                """
                                compute_admin_score = _load_scoring_engine()
                                return compute_admin_score(model_admin_class)

Pourquoi cette façade est importante ?

Préparer l'environnement

cd path/to/project

                                python -m venv .venv

                                # Windows
                                .venv\Scripts\activate.bat

                                # Linux / macOS
                                source .venv/bin/activate

                                python -m pip install --upgrade pip setuptools wheel
                                python -m pip install -U nuitka ordered-set zstandard

Compiler scoring.py

python -m nuitka \
                                --mode=module \
                                --output-dir=build/nuitka_modules \
                                --remove-output \
                                --show-progress \
                                --report=build/nuitka_modules/scoring-report.xml \
                                ideolab_admin_tools/protected_core/scoring.py

Résultats attendus

build/nuitka_modules/
                                │
                                ├── scoring.build/
                                │   └── fichiers intermédiaires C/C++
                                │
                                └── scoring.cp312-win_amd64.pyd
                                ou
                                └── scoring.cpython-312-x86_64-linux-gnu.so

Copie dans l'addon

# Exemple Windows
                                copy build\nuitka_modules\scoring*.pyd ideolab_admin_tools\protected_core\

                                # Exemple Linux / macOS
                                cp build/nuitka_modules/scoring*.so ideolab_admin_tools/protected_core/

MANIFEST.in

recursive-include ideolab_admin_tools/templates *
                                recursive-include ideolab_admin_tools/static *
                                recursive-include ideolab_admin_tools/protected_core *.pyd
                                recursive-include ideolab_admin_tools/protected_core *.so
                                recursive-include ideolab_admin_tools/protected_core *.dll
                                recursive-include ideolab_admin_tools/protected_core/rules *.json
                                recursive-exclude ideolab_admin_tools/protected_core *_dev.py
                                recursive-exclude ideolab_admin_tools/protected_core *_scratch.py
                                recursive-exclude tests *
                                recursive-exclude docs/internal *

pyproject.toml indicatif

[build-system]
                                requires = ["setuptools", "wheel"]
                                build-backend = "setuptools.build_meta"

                                [tool.setuptools]
                                include-package-data = true

                                [tool.setuptools.packages.find]
                                include = ["ideolab_admin_tools*"]

Ce qu'il faut livrer

Règle recommandée

Variables d'environnement

# Dev seulement
                                IDEOLAB_ADMIN_TOOLS_ALLOW_PY_FALLBACK=1

                                # Staging / Production
                                IDEOLAB_ADMIN_TOOLS_ALLOW_PY_FALLBACK=0

                                # Optionnel : vérifier mode strict
                                IDEOLAB_ADMIN_TOOLS_REQUIRE_COMPILED_CORE=1

Commandes de test

# Vérifier l'import direct du module compilé
                                python -c "import ideolab_admin_tools.protected_core.scoring; print('import OK')"

                                # Vérifier l'API publique
                                python -c "from ideolab_admin_tools.core_api import score_model_admin; print(score_model_admin)"

                                # Checks Django
                                python manage.py check

                                # Tests de l'app
                                python manage.py test ideolab_admin_tools

                                # Lancer le serveur
                                python manage.py runserver

Tests manuels Admin

Pipeline de release

Release pipeline
                                │
                                ├── 1. Clean workspace
                                ├── 2. Run source tests
                                ├── 3. Build compiled modules
                                ├── 4. Copy .pyd / .so into package
                                ├── 5. Remove sensitive .py sources if needed
                                ├── 6. Build wheel / archive
                                ├── 7. Install into clean venv
                                ├── 8. Run Django checks
                                ├── 9. Run admin smoke tests
                                └── 10. Tag release

Checklist release

Premier module recommandé

# ideolab_admin_tools/protected_core/scoring.py

                                from __future__ import annotations
                                from typing import Any


                                def compute_admin_score(model_admin_class: type[Any]) -> dict[str, Any]:
                                score = 0
                                signals = []

                                if hasattr(model_admin_class, "list_display"):
                                score += 10
                                signals.append("list_display")

                                if hasattr(model_admin_class, "search_fields"):
                                score += 10
                                signals.append("search_fields")

                                if hasattr(model_admin_class, "list_filter"):
                                score += 10
                                signals.append("list_filter")

                                return {
                                "score": score,
                                "signals": signals,
                                "level": "advanced" if score >= 25 else "basic",
                                }

Commande de premier essai

python -m nuitka \
                                --mode=module \
                                --output-dir=build/nuitka_modules \
                                --remove-output \
                                --show-progress \
                                ideolab_admin_tools/protected_core/scoring.py

                                python -c "import ideolab_admin_tools.protected_core.scoring; print('OK')"

                                python manage.py check

Inventaire recommandé

project/
                                │
                                ├── config/
                                │   └── defaults.yaml
                                │
                                ├── rules/
                                │   ├── default_rules.json
                                │   └── admin_scoring.json
                                │
                                ├── templates/
                                │   └── report.html
                                │
                                ├── static/
                                │   ├── css/app.css
                                │   └── js/app.js
                                │
                                ├── certs/
                                │   └── ca.pem
                                │
                                └── plugins/
                                ├── csv_exporter.py
                                └── html_exporter.py

À ne jamais inclure par erreur

Inclure des fichiers et dossiers

python -m nuitka \
                                --mode=standalone \
                                --output-dir=build/nuitka \
                                --include-data-files=config/defaults.yaml=config/defaults.yaml \
                                --include-data-files=rules/*.json=rules/ \
                                --include-data-dir=templates=templates \
                                --include-data-dir=static=static \
                                app.py

Inclure des certificats

python -m nuitka \
                                --mode=standalone \
                                --include-data-files=certs/ca.pem=certs/ca.pem \
                                app.py

Inclure imports dynamiques

python -m nuitka \
                                --mode=standalone \
                                --include-module=my_package.dynamic_plugin \
                                --include-module=my_package.exporters.csv_exporter \
                                --include-package=my_package.rules \
                                app.py

Build avec rapport

python -m nuitka \
                                --mode=standalone \
                                --output-dir=build/nuitka \
                                --report=build/reports/data-report.xml \
                                --show-progress \
                                --include-data-dir=templates=templates \
                                --include-data-dir=static=static \
                                app.py

Mauvais pattern

from pathlib import Path

                                # Fragile : dépend du dossier depuis lequel on lance le programme
                                rules_path = Path("rules/default_rules.json")
                                content = rules_path.read_text(encoding="utf-8")

Pourquoi c'est fragile ?

• Le working directory peut changer.
• Le binaire peut être lancé depuis un autre dossier.
• Le mode onefile peut extraire les fichiers ailleurs.
• Le dossier source peut ne pas exister chez l'utilisateur final.

Meilleur pattern

from pathlib import Path
                                import sys


                                def runtime_base_dir() -> Path:
                                """
                                Return a robust base directory for source, standalone and onefile contexts.
                                """
                                if getattr(sys, "frozen", False):
                                return Path(sys.executable).resolve().parent

                                return Path(__file__).resolve().parent


                                def load_default_rules() -> str:
                                base_dir = runtime_base_dir()
                                rules_path = base_dir / "rules" / "default_rules.json"
                                return rules_path.read_text(encoding="utf-8")

Arborescence addon Django

ideolab_admin_tools/
                                │
                                ├── apps.py
                                ├── admin.py
                                ├── views.py
                                ├── urls.py
                                │
                                ├── templates/
                                │   └── ideolab_admin_tools/
                                │       ├── dashboard.html
                                │       ├── modal_detail.html
                                │       └── components/
                                │
                                ├── static/
                                │   └── ideolab_admin_tools/
                                │       ├── css/admin_tools.css
                                │       ├── js/admin_tools.js
                                │       └── img/logo.svg
                                │
                                └── protected_core/
                                ├── scoring.pyd / scoring.so
                                └── rules/
                                └── default_rules.json

Packaging Django classique

# MANIFEST.in
                                recursive-include ideolab_admin_tools/templates *
                                recursive-include ideolab_admin_tools/static *
                                recursive-include ideolab_admin_tools/protected_core *.pyd
                                recursive-include ideolab_admin_tools/protected_core *.so
                                recursive-include ideolab_admin_tools/protected_core/rules *.json
                                recursive-exclude tests *
                                recursive-exclude docs/internal *

pyproject.toml

[tool.setuptools]
                                include-package-data = true

                                [tool.setuptools.packages.find]
                                include = ["ideolab_admin_tools*"]

Exemple fragile

import importlib

                                PLUGIN_NAME = "myapp.plugins.csv_exporter"

                                plugin_module = importlib.import_module(PLUGIN_NAME)
                                plugin_module.run()

Ici, le module est chargé par son nom texte. Dans un système réel, ce nom peut venir d'un fichier YAML, d'un setting Django, d'une base de données ou d'un registre de plugins.

Commande de correction

python -m nuitka \
                                --mode=standalone \
                                --include-module=myapp.plugins.csv_exporter \
                                --include-module=myapp.plugins.html_exporter \
                                --include-package=myapp.rules \
                                app.py

Dépendances natives typiques

Diagnostic natif

Runtime native error
                                │
                                ├── Windows
                                │   ├── DLL load failed
                                │   ├── missing .dll
                                │   └── inspect .dist folder
                                │
                                ├── Linux
                                │   ├── cannot open shared object file
                                │   ├── ldd executable
                                │   └── check .so presence
                                │
                                └── macOS
                                ├── dylib not loaded
                                ├── otool -L executable
                                └── signing / quarantine issues

Linux

# Voir les dépendances natives
                                ldd build/nuitka/app.dist/app

                                # Chercher les .so livrées
                                find build/nuitka/app.dist -name "*.so*" -type f

Windows PowerShell

# Lister les DLL dans le standalone
                                Get-ChildItem -Recurse build\nuitka\app.dist -Filter *.dll

                                # Vérifier la présence de l'exécutable
                                Get-ChildItem build\nuitka\app.dist

Livrable standalone

release/
                                │
                                ├── app.dist/
                                │   ├── app.exe / app
                                │   ├── config/
                                │   │   └── defaults.yaml
                                │   ├── rules/
                                │   │   └── default_rules.json
                                │   ├── templates/
                                │   ├── static/
                                │   ├── *.dll / *.so / *.dylib
                                │   └── runtime files
                                │
                                └── README_RUN.txt

Livrable addon Django

wheel contents
                                │
                                ├── ideolab_admin_tools/
                                │   ├── apps.py
                                │   ├── admin.py
                                │   ├── views.py
                                │   ├── templates/
                                │   ├── static/
                                │   └── protected_core/
                                │       ├── scoring.pyd / scoring.so
                                │       └── rules/default_rules.json
                                │
                                └── metadata

Évolution recommandée

Étape 1
                                Source Python interne
                                │
                                ▼
                                Étape 2
                                Identifier le cœur métier
                                │
                                ▼
                                Étape 3
                                Créer une API publique stable
                                │
                                ▼
                                Étape 4
                                Compiler le cœur avec Nuitka
                                │
                                ▼
                                Étape 5
                                Retirer les sources sensibles du livrable
                                │
                                ▼
                                Étape 6
                                Tester la wheel / release propre
                                │
                                ▼
                                Étape 7
                                Ajouter licence, contrat, activation si nécessaire

Erreur fréquente

Livrable propre

release_package/
                                │
                                ├── public Python layer
                                │   ├── admin.py
                                │   ├── views.py
                                │   └── core_api.py
                                │
                                ├── protected binary layer
                                │   ├── scoring.pyd / scoring.so
                                │   ├── analyzer.pyd / analyzer.so
                                │   └── rules_engine.pyd / rules_engine.so
                                │
                                └── resources
                                ├── templates/
                                ├── static/
                                └── safe rules/config

Menaces réduites par Nuitka

• Copie directe des fichiers .py sensibles.
• Lecture rapide des heuristiques internes.
• Décompilation simple du bytecode Python.
• Modification naïve de fonctions métier.
• Distribution d'une copie quasi identique du moteur.

Menaces non résolues par Nuitka seul

• Analyse binaire avancée par personne motivée.
• Extraction de chaînes texte présentes dans le binaire.
• Vol de secrets codés en dur.
• Contournement logique si la licence est uniquement locale.
• Copie de l'interface publique et imitation du comportement.

Architecture recommandée

Public layer
                                │
                                ├── admin.py
                                ├── views.py
                                ├── urls.py
                                ├── apps.py
                                ├── templates/
                                ├── static/
                                └── core_api.py
                                │
                                │ calls stable API
                                ▼
                                Protected layer
                                │
                                ├── scoring.pyd / scoring.so
                                ├── analyzer.pyd / analyzer.so
                                ├── rules_engine.pyd / rules_engine.so
                                └── metadata_builder.pyd / metadata_builder.so
                                │
                                │ reads safe resources
                                ▼
                                Resources
                                │
                                ├── public templates
                                ├── public static assets
                                └── non-secret rules/config

Responsabilités par couche

Bénéfices directs

• Suppression de la distribution directe des fichiers .py pour les modules compilés.
• Barrière technique plus forte que du bytecode Python .pyc.
• Packaging plus professionnel pour un addon distribué.
• Possibilité de garder une interface Python lisible et de cacher le noyau.
• Réduction du risque de copie immédiate des algorithmes.
• Compatible avec une architecture progressive : un module à la fois.

Commande typique

python -m nuitka \
                                --mode=module \
                                --output-dir=build/nuitka_modules \
                                --remove-output \
                                --show-progress \
                                protected_core/scoring.py

Avant / après

Ce qui reste exposé

• Les noms publics appelés depuis la couche Python.
• Certains messages d'erreur ou chaînes de caractères.
• Les comportements observables du moteur.
• Les endpoints et interfaces visibles.
• Les fichiers data livrés comme JSON/YAML.

Comment réduire l'exposition

• Limiter l'API publique.
• Éviter les noms trop révélateurs dans les fonctions publiques.
• Ne pas mettre de secrets dans le code.
• Nettoyer la release avant livraison.
• Déplacer les décisions très critiques côté serveur.

À ne jamais faire

# Mauvais exemple : secret codé en dur
                                MASTER_LICENSE_KEY = "ABC-SECRET-PRIVATE-KEY"

                                API_TOKEN = "sk_live_xxxxxxxxxxxxxxxxx"

                                def validate_license(user_key: str) -> bool:
                                return user_key == MASTER_LICENSE_KEY

Approches plus sûres

Pattern licence locale raisonnable

Client installation
                                │
                                ├── compiled addon
                                ├── public license file
                                │   └── signed entitlement
                                │
                                └── local verifier
                                ├── checks signature
                                ├── checks expiry
                                └── never contains master private key

Structure recommandée

ideolab_admin_tools/
                                │
                                ├── public layer
                                │   ├── apps.py
                                │   ├── admin.py
                                │   ├── views.py
                                │   ├── urls.py
                                │   ├── templates/
                                │   └── static/
                                │
                                ├── bridge
                                │   ├── core_api.py
                                │   ├── dto.py
                                │   └── normalizers.py
                                │
                                └── protected_core/
                                ├── scoring.pyd / scoring.so
                                ├── analyzer.pyd / analyzer.so
                                ├── rules_engine.pyd / rules_engine.so
                                └── metadata_builder.pyd / metadata_builder.so

Ce qui doit rester public

Ce qui doit être protégé

• Scoring avancé des ModelAdmin.
• Heuristiques de diagnostic.
• Règles de classification des problèmes.
• Analyse d'introspection propriétaire.
• Génération de recommandations.

Pipeline de release sécurisé

Release sécurisée
                                │
                                ├── 1. Tests source internes
                                ├── 2. Build Nuitka modules
                                ├── 3. Copie .pyd / .so
                                ├── 4. Suppression sources sensibles du livrable
                                ├── 5. Inclusion templates/static nécessaires
                                ├── 6. Exclusion .env, tests, docs internes
                                ├── 7. Build wheel / archive
                                ├── 8. Installation dans venv propre
                                ├── 9. Test import compiled core
                                ├── 10. Test Django admin
                                └── 11. Inspection manuelle du contenu final

À exclure impérativement

Phrase recommandée

Phrase à éviter

Structure projet

project/
                                │
                                ├── app.py
                                ├── pyproject.toml
                                ├── requirements.txt
                                ├── requirements-build.txt
                                │
                                ├── src/
                                │   └── my_package/
                                │
                                ├── tests/
                                │   ├── test_source.py
                                │   ├── test_binary.py
                                │   └── test_packaging.py
                                │
                                ├── scripts/
                                │   ├── build_nuitka.py
                                │   ├── build_windows.ps1
                                │   ├── build_linux.sh
                                │   ├── clean_build.py
                                │   └── validate_artifact.py
                                │
                                ├── build/
                                │   ├── nuitka/
                                │   ├── logs/
                                │   ├── reports/
                                │   └── tmp/
                                │
                                ├── dist/
                                │   ├── releases/
                                │   └── wheels/
                                │
                                └── .github/
                                └── workflows/
                                └── nuitka-build.yml

Rôle des dossiers

Exemple .gitignore

# Build outputs
                                build/
                                dist/
                                *.build/
                                *.dist/
                                *.onefile-build/

                                # Python
                                __pycache__/
                                *.pyc
                                .venv/

                                # Secrets
                                .env
                                *.key
                                *.pem

                                # Nuitka local reports
                                *.log
                                *.xml

Makefile complet

PYTHON ?= python
                                APP ?= app.py
                                APP_NAME ?= app
                                OUT ?= build/nuitka
                                LOGS ?= build/logs
                                REPORTS ?= build/reports
                                DIST ?= dist/releases
                                JOBS ?= 8

                                .PHONY: help clean env test check build-standalone build-onefile validate package release

                                help:
                                @echo "Available targets:"
                                @echo "  make clean"
                                @echo "  make env"
                                @echo "  make test"
                                @echo "  make build-standalone"
                                @echo "  make build-onefile"
                                @echo "  make validate"
                                @echo "  make release"

                                clean:
                                rm -rf $(OUT) $(LOGS) $(REPORTS)
                                rm -rf *.build *.dist *.onefile-build
                                mkdir -p $(OUT) $(LOGS) $(REPORTS) $(DIST)

                                env:
                                $(PYTHON) -m pip install --upgrade pip setuptools wheel
                                $(PYTHON) -m pip install -r requirements-build.txt

                                test:
                                $(PYTHON) -m pytest -v

                                check:
                                $(PYTHON) -m compileall .

                                build-standalone: clean test
                                $(PYTHON) -m nuitka \
                                --mode=standalone \
                                --output-dir=$(OUT) \
                                --remove-output \
                                --jobs=$(JOBS) \
                                --show-progress \
                                --report=$(REPORTS)/standalone-report.xml \
                                --assume-yes-for-downloads \
                                $(APP) 2>&1 | tee $(LOGS)/standalone-build.log

                                build-onefile: clean test
                                $(PYTHON) -m nuitka \
                                --mode=onefile \
                                --output-dir=$(OUT) \
                                --remove-output \
                                --jobs=$(JOBS) \
                                --show-progress \
                                --report=$(REPORTS)/onefile-report.xml \
                                --assume-yes-for-downloads \
                                $(APP) 2>&1 | tee $(LOGS)/onefile-build.log

                                validate:
                                $(PYTHON) scripts/validate_artifact.py

                                package:
                                cd $(OUT) && zip -r ../../$(DIST)/$(APP_NAME)-standalone.zip $(APP_NAME).dist

                                release: build-standalone validate package
                                sha256sum $(DIST)/* > $(DIST)/SHA256SUMS.txt
                                @echo "Release ready in $(DIST)"

Commandes d'utilisation

# Installer l'environnement de build
                                make env

                                # Lancer les tests
                                make test

                                # Compiler standalone
                                make build-standalone

                                # Compiler onefile
                                make build-onefile

                                # Valider l'artefact
                                make validate

                                # Construire une release complète
                                make release

Variables utiles

Script scripts/build_windows.ps1

param(
                                [string]$App = "app.py",
                                [string]$AppName = "app",
                                [string]$OutputDir = "build\nuitka",
                                [string]$LogsDir = "build\logs",
                                [string]$ReportsDir = "build\reports",
                                [int]$Jobs = 8,
                                [switch]$Onefile
                                )

                                $ErrorActionPreference = "Stop"

                                Write-Host "=== Nuitka Windows Build ===" -ForegroundColor Cyan
                                Write-Host "App: $App"
                                Write-Host "Mode: $(if ($Onefile) { 'onefile' } else { 'standalone' })"

                                New-Item -ItemType Directory -Force $OutputDir, $LogsDir, $ReportsDir | Out-Null

                                Write-Host "Installing build requirements..." -ForegroundColor Yellow
                                python -m pip install --upgrade pip setuptools wheel
                                python -m pip install -r requirements-build.txt

                                Write-Host "Running tests..." -ForegroundColor Yellow
                                python -m pytest -v

                                $Mode = if ($Onefile) { "onefile" } else { "standalone" }
                                $Report = Join-Path $ReportsDir "$Mode-report.xml"
                                $Log = Join-Path $LogsDir "$Mode-build.log"

                                Write-Host "Building with Nuitka..." -ForegroundColor Yellow

                                $Arguments = @(
                                "-m", "nuitka",
                                "--mode=$Mode",
                                "--output-dir=$OutputDir",
                                "--remove-output",
                                "--jobs=$Jobs",
                                "--show-progress",
                                "--report=$Report",
                                "--assume-yes-for-downloads",
                                $App
                                )

                                python @Arguments *>&1 | Tee-Object $Log

                                if ($LASTEXITCODE -ne 0) {
                                throw "Nuitka build failed with exit code $LASTEXITCODE"
                                }

                                Write-Host "Build completed successfully." -ForegroundColor Green
                                Write-Host "Log: $Log"
                                Write-Host "Report: $Report"

Utilisation

# Standalone
                                .\scripts\build_windows.ps1 `
                                -App "app.py" `
                                -AppName "app" `
                                -Jobs 8

                                # Onefile
                                .\scripts\build_windows.ps1 `
                                -App "app.py" `
                                -AppName "app" `
                                -Jobs 8 `
                                -Onefile

Script de validation Windows

# scripts/validate_windows.ps1
                                $ErrorActionPreference = "Stop"

                                $Binary = "build\nuitka\app.dist\app.exe"

                                if (!(Test-Path $Binary)) {
                                throw "Binary not found: $Binary"
                                }

                                & $Binary

                                if ($LASTEXITCODE -ne 0) {
                                throw "Binary failed with exit code $LASTEXITCODE"
                                }

                                Write-Host "Binary validation OK" -ForegroundColor Green

Script scripts/build_nuitka.py

from __future__ import annotations

                                import argparse
                                import platform
                                import shutil
                                import subprocess
                                import sys
                                from pathlib import Path


                                ROOT = Path(__file__).resolve().parent.parent
                                BUILD_DIR = ROOT / "build"
                                NUITKA_DIR = BUILD_DIR / "nuitka"
                                LOGS_DIR = BUILD_DIR / "logs"
                                REPORTS_DIR = BUILD_DIR / "reports"


                                def run(command: list[str], log_file: Path | None = None) -> None:
                                print("+", " ".join(command))

                                if log_file is None:
                                result = subprocess.run(command, cwd=ROOT)
                                if result.returncode != 0:
                                raise SystemExit(result.returncode)
                                return

                                with log_file.open("w", encoding="utf-8") as stream:
                                process = subprocess.Popen(
                                command,
                                cwd=ROOT,
                                stdout=subprocess.PIPE,
                                stderr=subprocess.STDOUT,
                                text=True,
                                )

                                assert process.stdout is not None

                                for line in process.stdout:
                                print(line, end="")
                                stream.write(line)

                                code = process.wait()
                                if code != 0:
                                raise SystemExit(code)


                                def clean() -> None:
                                for path in [NUITKA_DIR, LOGS_DIR, REPORTS_DIR]:
                                if path.exists():
                                shutil.rmtree(path)
                                path.mkdir(parents=True, exist_ok=True)


                                def write_environment_report() -> None:
                                REPORTS_DIR.mkdir(parents=True, exist_ok=True)

                                content = [
                                f"platform={platform.platform()}",
                                f"machine={platform.machine()}",
                                f"python={sys.version}",
                                f"executable={sys.executable}",
                                ]

                                (REPORTS_DIR / "environment.txt").write_text("\n".join(content), encoding="utf-8")


                                def main() -> int:
                                parser = argparse.ArgumentParser()
                                parser.add_argument("--app", default="app.py")
                                parser.add_argument("--mode", choices=["standalone", "onefile", "module"], default="standalone")
                                parser.add_argument("--jobs", default="8")
                                parser.add_argument("--skip-tests", action="store_true")
                                args = parser.parse_args()

                                clean()
                                write_environment_report()

                                run([sys.executable, "-m", "pip", "install", "-r", "requirements-build.txt"])

                                if not args.skip_tests:
                                run([sys.executable, "-m", "pytest", "-v"])

                                report = REPORTS_DIR / f"{args.mode}-report.xml"
                                log = LOGS_DIR / f"{args.mode}-build.log"

                                command = [
                                sys.executable,
                                "-m",
                                "nuitka",
                                f"--mode={args.mode}",
                                f"--output-dir={NUITKA_DIR}",
                                "--remove-output",
                                f"--jobs={args.jobs}",
                                "--show-progress",
                                f"--report={report}",
                                "--assume-yes-for-downloads",
                                args.app,
                                ]

                                run(command, log_file=log)

                                print("Build OK")
                                print(f"Log: {log}")
                                print(f"Report: {report}")

                                return 0


                                if __name__ == "__main__":
                                raise SystemExit(main())

Utilisation

# Build standalone
                                python scripts/build_nuitka.py --app app.py --mode standalone

                                # Build onefile
                                python scripts/build_nuitka.py --app app.py --mode onefile

                                # Build module
                                python scripts/build_nuitka.py \
                                --app ideolab_admin_tools/protected_core/scoring.py \
                                --mode module

                                # Build sans relancer pytest
                                python scripts/build_nuitka.py --app app.py --mode standalone --skip-tests

Avantages du script Python

Workflow standalone Windows

name: nuitka-build-windows

                                on:
                                push:
                                branches: ["main"]
                                pull_request:
                                workflow_dispatch:

                                jobs:
                                build-windows:
                                runs-on: windows-latest

                                steps:
                                - name: Checkout
                                uses: actions/checkout@v4

                                - name: Setup Python
                                uses: actions/setup-python@v5
                                with:
                                python-version: "3.12"

                                - name: Install build dependencies
                                run: |
                                python -m pip install --upgrade pip setuptools wheel
                                python -m pip install -r requirements-build.txt

                                - name: Run tests
                                run: |
                                python -m pytest -v

                                - name: Build with Nuitka
                                run: |
                                python -m nuitka `
                                --mode=standalone `
                                --output-dir=build\nuitka `
                                --remove-output `
                                --show-progress `
                                --report=build\reports\compilation-report.xml `
                                --assume-yes-for-downloads `
                                app.py

                                - name: Upload Nuitka artifact
                                uses: actions/upload-artifact@v4
                                with:
                                name: app-windows-standalone
                                path: |
                                build/nuitka/**/*.dist/**
                                build/reports/**
                                build/logs/**
                                if-no-files-found: error

Workflow Linux standalone

name: nuitka-build-linux

                                on:
                                push:
                                branches: ["main"]
                                pull_request:
                                workflow_dispatch:

                                jobs:
                                build-linux:
                                runs-on: ubuntu-latest

                                steps:
                                - name: Checkout
                                uses: actions/checkout@v4

                                - name: Install system packages
                                run: |
                                sudo apt update
                                sudo apt install -y build-essential ccache patchelf zip

                                - name: Setup Python
                                uses: actions/setup-python@v5
                                with:
                                python-version: "3.12"

                                - name: Install build dependencies
                                run: |
                                python -m pip install --upgrade pip setuptools wheel
                                python -m pip install -r requirements-build.txt

                                - name: Run tests
                                run: |
                                python -m pytest -v

                                - name: Build with Nuitka
                                run: |
                                mkdir -p build/logs build/reports
                                python -m nuitka \
                                --mode=standalone \
                                --output-dir=build/nuitka \
                                --remove-output \
                                --show-progress \
                                --report=build/reports/compilation-report.xml \
                                --assume-yes-for-downloads \
                                app.py 2>&1 | tee build/logs/build.log

                                - name: Upload Nuitka artifact
                                uses: actions/upload-artifact@v4
                                with:
                                name: app-linux-standalone
                                path: |
                                build/nuitka/**/*.dist/**
                                build/reports/**
                                build/logs/**
                                if-no-files-found: error

Workflow matrix

name: nuitka-matrix-build

                                on:
                                workflow_dispatch:
                                push:
                                tags:
                                - "v*"

                                jobs:
                                build:
                                strategy:
                                fail-fast: false
                                matrix:
                                os: [windows-latest, ubuntu-latest]
                                python-version: ["3.11", "3.12"]

                                runs-on: $

                                steps:
                                - uses: actions/checkout@v4

                                - name: Install Linux system packages
                                if: runner.os == 'Linux'
                                run: |
                                sudo apt update
                                sudo apt install -y build-essential ccache patchelf zip

                                - uses: actions/setup-python@v5
                                with:
                                python-version:  matrix.python-version 

                                - name: Install dependencies
                                run: |
                                python -m pip install --upgrade pip setuptools wheel
                                python -m pip install -r requirements-build.txt

                                - name: Run tests
                                run: |
                                python -m pytest -v

                                - name: Build with Python script
                                run: |
                                python scripts/build_nuitka.py --app app.py --mode standalone

                                - name: Upload artifact
                                uses: actions/upload-artifact@v4
                                with:
                                name: app-$-py$ matrix.python-version 
                                path: |
                                build/nuitka/**
                                build/reports/**
                                build/logs/**
                                if-no-files-found: error

Résultat attendu

CI artifacts
                                │
                                ├── app-Windows-py3.11
                                ├── app-Windows-py3.12
                                ├── app-Linux-py3.11
                                └── app-Linux-py3.12

Pourquoi plusieurs artefacts ?

Convention de nommage

dist/releases/
                                │
                                ├── ideolab-admin-tools-0.1.0-windows-amd64-py312-module.zip
                                ├── ideolab-admin-tools-0.1.0-linux-x86_64-py312-module.zip
                                ├── ideolab-cli-0.1.0-windows-amd64-py312-standalone.zip
                                ├── ideolab-cli-0.1.0-linux-x86_64-py312-standalone.zip
                                ├── SHA256SUMS.txt
                                ├── RELEASE_NOTES.md
                                └── validation-report.md

Métadonnées à conserver

Linux / macOS

mkdir -p dist/releases

                                cd build/nuitka
                                zip -r ../../dist/releases/app-linux-x86_64-py312-standalone.zip app.dist
                                cd ../..

                                sha256sum dist/releases/*.zip > dist/releases/SHA256SUMS.txt

Windows PowerShell

New-Item -ItemType Directory -Force dist\releases

                                Compress-Archive `
                                -Path build\nuitka\app.dist `
                                -DestinationPath dist\releases\app-windows-amd64-py312-standalone.zip `
                                -Force

                                Get-FileHash dist\releases\*.zip -Algorithm SHA256 |
                                Format-Table -AutoSize |
                                Out-File dist\releases\SHA256SUMS.txt

Template release notes

# Release 0.1.0

                                ## Artefacts
                                - Windows standalone Python 3.12
                                - Linux standalone Python 3.12

                                ## Build environment
                                - Python:
                                - Nuitka:
                                - OS:
                                - Compiler:

                                ## Validation
                                - Source tests: OK
                                - Nuitka build: OK
                                - Binary smoke test: OK
                                - Packaging inspection: OK

                                ## Known limitations
                                - Onefile not provided in this release.
                                - Build must match target OS and Python ABI.

                                ## SHA256
                                See SHA256SUMS.txt

Tag Git recommandé

# Créer un tag versionné
                                git tag -a v0.1.0 -m "Release v0.1.0 - Nuitka standalone build"

                                # Pousser le tag
                                git push origin v0.1.0

Définition d'un build “propre”

Build propre
                                │
                                ├── script versionné
                                ├── environnement documenté
                                ├── tests exécutés
                                ├── Nuitka report généré
                                ├── logs conservés
                                ├── artefact testé
                                ├── archive nommée
                                ├── SHA256 calculé
                                └── release notes écrites

Pour IDEO-Lab

Commandes de vérification

# Commun
                                python -m nuitka --version
                                python -c "import sys; print(sys.version); print(sys.executable)"

                                # Linux
                                gcc --version
                                g++ --version
                                which gcc
                                which g++

                                # Windows
                                where python
                                where pip

                                # Windows : vérifier depuis Developer Command Prompt si nécessaire
                                cl

Installation Linux / Ubuntu

sudo apt update
                                sudo apt install -y build-essential ccache patchelf

                                gcc --version
                                g++ --version

Correctifs par plateforme

Exemple fragile

import importlib

                                plugin_name = "myapp.plugins.csv_exporter"
                                plugin = importlib.import_module(plugin_name)
                                plugin.run()

Correctif Nuitka

python -m nuitka \
                                --mode=standalone \
                                --include-module=myapp.plugins.csv_exporter \
                                --include-module=myapp.plugins.html_exporter \
                                app.py

Diagnostic imports

Options correctives

# Inclure un fichier de config
                                python -m nuitka \
                                --mode=standalone \
                                --include-data-files=config/default.yaml=config/default.yaml \
                                app.py

                                # Inclure des règles JSON
                                python -m nuitka \
                                --mode=standalone \
                                --include-data-files=rules/*.json=rules/ \
                                app.py

                                # Inclure dossiers templates et static
                                python -m nuitka \
                                --mode=standalone \
                                --include-data-dir=templates=templates \
                                --include-data-dir=static=static \
                                app.py

Matrice symptômes / solutions

Commandes d'inspection

# Linux : voir les dépendances natives
                                ldd build/nuitka/app.dist/app

                                # Linux : chercher les .so
                                find build/nuitka/app.dist -name "*.so*" -type f

                                # Windows PowerShell : lister les DLL
                                Get-ChildItem -Recurse build\nuitka\app.dist -Filter *.dll

                                # macOS : dépendances
                                otool -L build/nuitka/app.dist/app

Erreurs typiques

Cycle onefile

onefile.exe / onefile.bin
                                │
                                ├── Start
                                ├── Create / use temporary extraction area
                                ├── Extract internal payload
                                ├── Launch compiled program
                                ├── Program reads files / imports modules
                                └── Cleanup / exit

Commande de build

python -m nuitka \
                                --mode=onefile \
                                --output-dir=build/nuitka \
                                --remove-output \
                                --show-progress \
                                --report=build/reports/onefile-report.xml \
                                --assume-yes-for-downloads \
                                app.py

Problèmes fréquents onefile

Checklist Windows

Antivirus / SmartScreen

Vérifier environnement

python -c "import sys; print(sys.version)"
                                python -c "import sys; print(sys.executable)"
                                python -c "import platform; print(platform.platform()); print(platform.machine())"
                                python -m nuitka --version

Nom typique d'extension

Windows:
                                scoring.cp312-win_amd64.pyd

                                Linux:
                                scoring.cpython-312-x86_64-linux-gnu.so

                                macOS:
                                scoring.cpython-312-darwin.so

Risques fréquents

Optimiser le temps de build

# Utiliser plusieurs jobs
                                python -m nuitka \
                                --mode=standalone \
                                --jobs=8 \
                                --show-progress \
                                app.py

                                # Linux : installer ccache
                                sudo apt install -y ccache
                                ccache --show-stats

                                # Observer mémoire
                                python -m nuitka \
                                --mode=standalone \
                                --show-memory \
                                app.py

Mesurer runtime

# Linux / macOS
                                /usr/bin/time -v python app.py
                                /usr/bin/time -v ./build/nuitka/app.dist/app

                                # Windows PowerShell
                                Measure-Command { python .\app.py }
                                Measure-Command { .\build\nuitka\app.dist\app.exe }

Commande diagnostic complète

python -m nuitka \
                                --mode=standalone \
                                --output-dir=build/nuitka \
                                --remove-output \
                                --show-progress \
                                --show-memory \
                                --report=build/reports/troubleshooting-report.xml \
                                --assume-yes-for-downloads \
                                --include-package=my_package \
                                app.py

Rapport à conserver

build/
                                │
                                ├── logs/
                                │   └── build.log
                                │
                                ├── reports/
                                │   ├── troubleshooting-report.xml
                                │   ├── environment.txt
                                │   └── validation-report.md
                                │
                                └── nuitka/
                                └── app.dist/

Step 1 — environnement

# Create virtual environment
                                python -m venv .venv

                                # Windows CMD
                                .venv\Scripts\activate.bat

                                # Linux / macOS
                                source .venv/bin/activate

                                # Upgrade packaging tools
                                python -m pip install --upgrade pip setuptools wheel

                                # Install Nuitka
                                python -m pip install -U nuitka ordered-set zstandard

                                # Verify
                                python -m nuitka --version

Vérifications système

# Linux
                                gcc --version
                                g++ --version

                                # Windows
                                where python
                                python --version
                                python -m nuitka --version

Step 2 — hello build

# hello_nuitka.py
                                from __future__ import annotations

                                import sys


                                def main() -> int:
                                print("hello from Nuitka")
                                print(f"python={sys.version.split()[0]}")
                                return 0


                                if __name__ == "__main__":
                                raise SystemExit(main())

# Run source
                                python hello_nuitka.py

                                # Compile
                                python -m nuitka hello_nuitka.py

                                # Run binary
                                # Windows
                                hello_nuitka.exe

                                # Linux / macOS
                                ./hello_nuitka

Step 3 — script réaliste

from __future__ import annotations

                                import platform
                                import sys
                                from pathlib import Path


                                def compute_score(values: list[int]) -> int:
                                return sum(value * 3 for value in values) + 17


                                def main() -> int:
                                print("Nuitka realistic smoke test")
                                print(f"python={sys.version.split()[0]}")
                                print(f"platform={platform.system()} {platform.machine()}")
                                print(f"cwd={Path.cwd()}")
                                print(f"score={compute_score([1, 2, 3, 4])}")
                                return 0


                                if __name__ == "__main__":
                                raise SystemExit(main())

python realistic_test.py
                                python -m nuitka realistic_test.py
                                ./realistic_test

Step 4 — standalone

python -m nuitka \
                                --mode=standalone \
                                --output-dir=build/nuitka \
                                --remove-output \
                                --show-progress \
                                --report=build/reports/standalone-report.xml \
                                --assume-yes-for-downloads \
                                realistic_test.py

Tester hors dossier source

# Linux / macOS
                                mkdir -p /tmp/nuitka_standalone_test
                                cp -r build/nuitka/realistic_test.dist /tmp/nuitka_standalone_test/
                                cd /tmp/nuitka_standalone_test/realistic_test.dist
                                ./realistic_test

                                # Windows PowerShell
                                New-Item -ItemType Directory -Force C:\temp\nuitka_standalone_test
                                Copy-Item -Recurse build\nuitka\realistic_test.dist C:\temp\nuitka_standalone_test\
                                cd C:\temp\nuitka_standalone_test\realistic_test.dist
                                .\realistic_test.exe

Commande onefile

python -m nuitka \
                                --mode=onefile \
                                --output-dir=build/nuitka \
                                --remove-output \
                                --show-progress \
                                --report=build/reports/onefile-report.xml \
                                --assume-yes-for-downloads \
                                realistic_test.py

Tester onefile

# Windows
                                build\nuitka\realistic_test.exe

                                # Linux / macOS
                                ./build/nuitka/realistic_test.bin

Décision onefile

Structure cible

ideolab_admin_tools/
                                │
                                ├── admin.py
                                ├── views.py
                                ├── apps.py
                                ├── core_api.py
                                │
                                └── protected_core/
                                ├── __init__.py
                                ├── scoring.py        -> source dev
                                ├── scoring_py.py     -> fallback dev optionnel
                                └── scoring.pyd/.so   -> module compilé release

Commande module

python -m nuitka \
                                --mode=module \
                                --output-dir=build/nuitka_modules \
                                --remove-output \
                                --show-progress \
                                --report=build/reports/scoring-module-report.xml \
                                ideolab_admin_tools/protected_core/scoring.py

Tests Django après compilation

# Copy compiled module into package
                                cp build/nuitka_modules/scoring*.so ideolab_admin_tools/protected_core/

                                # Direct import
                                python -c "import ideolab_admin_tools.protected_core.scoring; print('compiled import OK')"

                                # Django checks
                                python manage.py check

                                # App tests
                                python manage.py test ideolab_admin_tools

MANIFEST.in recommandé

recursive-include ideolab_admin_tools/templates *
                                recursive-include ideolab_admin_tools/static *
                                recursive-include ideolab_admin_tools/protected_core *.pyd
                                recursive-include ideolab_admin_tools/protected_core *.so
                                recursive-include ideolab_admin_tools/protected_core/rules *.json

                                recursive-exclude tests *
                                recursive-exclude docs/internal *
                                recursive-exclude ideolab_admin_tools/protected_core *_scratch.py
                                recursive-exclude ideolab_admin_tools/protected_core *_dev.py

Build wheel

python -m pip install build
                                python -m build

Test dans un venv propre

python -m venv /tmp/ideolab_addon_test
                                source /tmp/ideolab_addon_test/bin/activate

                                python -m pip install --upgrade pip
                                python -m pip install dist/ideolab_admin_tools-*.whl

                                python -c "import ideolab_admin_tools; print('addon import OK')"
                                python -c "import ideolab_admin_tools.protected_core.scoring; print('compiled core OK')"

Inspection de wheel

python -m zipfile -l dist/ideolab_admin_tools-*.whl

Go fort

• Venv propre OK.
• Build simple OK.
• Standalone OK hors repo.
• Module réel compilé OK.
• Import Django OK.
• Package installable OK.
• Sources sensibles absentes du livrable final.

No-Go temporaire

• Imports dynamiques non inclus.
• Fichiers data absents.
• DLL/SO manquantes.
• Onefile uniquement cassé.
• Fallback Python mal contrôlé.
• Wheel incomplète.

Ordre de travail

Phase A - Environment
                                │
                                ├── Create venv
                                ├── Install Nuitka
                                ├── Verify compiler
                                └── Compile hello

                                Phase B - Packaging basics
                                │
                                ├── Compile realistic script
                                ├── Compare source/binary
                                ├── Build standalone
                                └── Test outside repo

                                Phase C - Optional onefile
                                │
                                ├── Build onefile
                                ├── Test antivirus/runtime
                                └── Keep standalone if needed

                                Phase D - Real addon core
                                │
                                ├── Isolate protected_core/scoring.py
                                ├── Add core_api.py
                                ├── Compile module
                                ├── Import in Django
                                └── Run manage.py check

                                Phase E - Release
                                │
                                ├── Include .pyd/.so
                                ├── Include templates/static
                                ├── Remove sensitive sources
                                ├── Build wheel
                                ├── Install in clean venv
                                └── Inspect final package

Commandes de référence

# Step 1
                                python -m venv .venv
                                source .venv/bin/activate
                                python -m pip install -U pip setuptools wheel
                                python -m pip install -U nuitka ordered-set zstandard
                                python -m nuitka --version

                                # Step 2
                                python -m nuitka hello_nuitka.py

                                # Step 4
                                python -m nuitka \
                                --mode=standalone \
                                --output-dir=build/nuitka \
                                --remove-output \
                                --show-progress \
                                --report=build/reports/standalone-report.xml \
                                hello_nuitka.py

                                # Step 6
                                python -m nuitka \
                                --mode=module \
                                --output-dir=build/nuitka_modules \
                                --remove-output \
                                --show-progress \
                                ideolab_admin_tools/protected_core/scoring.py

                                # Step 7
                                python -m build
                                python -m zipfile -l dist/ideolab_admin_tools-*.whl

Build simple / accelerated

# Syntaxe courte
                                python -m nuitka app.py

                                # Syntaxe explicite
                                python -m nuitka --mode=accelerated app.py

                                # Avec dossier de sortie
                                python -m nuitka \
                                --mode=accelerated \
                                --output-dir=build/nuitka \
                                app.py

Standalone

python -m nuitka \
                                --mode=standalone \
                                --output-dir=build/nuitka \
                                --remove-output \
                                --show-progress \
                                --assume-yes-for-downloads \
                                app.py

Onefile

python -m nuitka \
                                --mode=onefile \
                                --output-dir=build/nuitka \
                                --remove-output \
                                --show-progress \
                                --assume-yes-for-downloads \
                                app.py

À éviter au début

# Trop direct : pas de standalone, pas de rapport, debug difficile
                                python -m nuitka --onefile app.py

Vérifier Python / venv / Nuitka

where python
                                where pip

                                python --version
                                python -m pip --version
                                python -m nuitka --version

                                python -c "import sys; print(sys.executable)"

Build standalone Windows

python -m nuitka `
                                --mode=standalone `
                                --output-dir=build\nuitka `
                                --remove-output `
                                --show-progress `
                                --assume-yes-for-downloads `
                                app.py

Build onefile Windows

python -m nuitka `
                                --mode=onefile `
                                --output-dir=build\nuitka `
                                --remove-output `
                                --show-progress `
                                --assume-yes-for-downloads `
                                app.py

Nettoyer les builds

Remove-Item -Recurse -Force build\nuitka -ErrorAction SilentlyContinue
                                Remove-Item -Recurse -Force build\logs -ErrorAction SilentlyContinue
                                Remove-Item -Recurse -Force build\reports -ErrorAction SilentlyContinue

Installation système

sudo apt update
                                sudo apt install -y python3 python3-venv python3-pip
                                sudo apt install -y build-essential ccache patchelf zip

Venv + Nuitka

python3 -m venv .venv
                                source .venv/bin/activate

                                python -m pip install --upgrade pip setuptools wheel
                                python -m pip install -U nuitka ordered-set zstandard

                                python -m nuitka --version

Build standalone Linux

mkdir -p build/logs build/reports

                                python -m nuitka \
                                --mode=standalone \
                                --output-dir=build/nuitka \
                                --remove-output \
                                --show-progress \
                                --report=build/reports/standalone-report.xml \
                                --assume-yes-for-downloads \
                                app.py 2>&1 | tee build/logs/standalone-build.log

Build onefile Linux

mkdir -p build/logs build/reports

                                python -m nuitka \
                                --mode=onefile \
                                --output-dir=build/nuitka \
                                --remove-output \
                                --show-progress \
                                --report=build/reports/onefile-report.xml \
                                --assume-yes-for-downloads \
                                app.py 2>&1 | tee build/logs/onefile-build.log

Tester hors repo

mkdir -p /tmp/nuitka_runtime_test
                                cp -r build/nuitka/app.dist /tmp/nuitka_runtime_test/
                                cd /tmp/nuitka_runtime_test/app.dist
                                ./app

Nettoyer

rm -rf build/nuitka build/logs build/reports
                                rm -rf *.build *.dist *.onefile-build

Commande module simple

python -m nuitka \
                                --mode=module \
                                --output-dir=build/nuitka_modules \
                                --remove-output \
                                --show-progress \
                                package/core_engine.py

Avec rapport

python -m nuitka \
                                --mode=module \
                                --output-dir=build/nuitka_modules \
                                --remove-output \
                                --show-progress \
                                --report=build/reports/core-engine-report.xml \
                                package/core_engine.py

Résultats typiques

Windows:
                                core_engine.cp312-win_amd64.pyd

                                Linux:
                                core_engine.cpython-312-x86_64-linux-gnu.so

                                macOS:
                                core_engine.cpython-312-darwin.so

Tester l'import

python -c "import package.core_engine; print('compiled import OK')"

Windows

copy build\nuitka_modules\core_engine*.pyd package\

Linux / macOS

cp build/nuitka_modules/core_engine*.so package/

Avec data files

python -m nuitka \
                                --mode=standalone \
                                --output-dir=build/nuitka \
                                --include-data-files=config.yaml=config.yaml \
                                --include-data-files=rules/*.json=rules/ \
                                app.py

Avec dossiers data

python -m nuitka \
                                --mode=standalone \
                                --output-dir=build/nuitka \
                                --include-data-dir=templates=templates \
                                --include-data-dir=static=static \
                                app.py

Avec imports dynamiques

python -m nuitka \
                                --mode=standalone \
                                --include-module=myapp.plugins.csv_exporter \
                                --include-module=myapp.plugins.html_exporter \
                                --include-package=myapp.rules \
                                app.py

Exclure du livrable

# Ne jamais inclure dans une release fermée :
                                # .env
                                # .git/
                                # tests/
                                # docs/internal/
                                # dev_config.yaml
                                # sources sensibles si remplacées par .pyd/.so

Compiler le cœur métier

python -m nuitka \
                                --mode=module \
                                --output-dir=build/nuitka_modules \
                                --remove-output \
                                --show-progress \
                                --report=build/reports/scoring-report.xml \
                                ideolab_admin_tools/protected_core/scoring.py

Copier extension compilée

# Windows
                                copy build\nuitka_modules\scoring*.pyd ideolab_admin_tools\protected_core\

                                # Linux / macOS
                                cp build/nuitka_modules/scoring*.so ideolab_admin_tools/protected_core/

Tests Django

python -c "import ideolab_admin_tools.protected_core.scoring; print('compiled core OK')"

                                python manage.py check

                                python manage.py test ideolab_admin_tools

                                python manage.py runserver

MANIFEST.in

recursive-include ideolab_admin_tools/templates *
                                recursive-include ideolab_admin_tools/static *
                                recursive-include ideolab_admin_tools/protected_core *.pyd
                                recursive-include ideolab_admin_tools/protected_core *.so
                                recursive-include ideolab_admin_tools/protected_core/rules *.json
                                recursive-exclude tests *
                                recursive-exclude docs/internal *

Diagnostic environnement

python -c "import sys; print(sys.version); print(sys.executable)"
                                python -m pip --version
                                python -m nuitka --version

                                # Linux
                                gcc --version
                                g++ --version
                                patchelf --version

                                # Windows
                                where python
                                where pip

Build avec rapport

python -m nuitka \
                                --mode=standalone \
                                --output-dir=build/nuitka \
                                --remove-output \
                                --show-progress \
                                --show-memory \
                                --report=build/reports/debug-report.xml \
                                --assume-yes-for-downloads \
                                app.py

Erreurs fréquentes

requirements-build.txt

nuitka
                                ordered-set
                                zstandard
                                setuptools
                                wheel
                                pytest
                                build

Build Python script

python scripts/build_nuitka.py \
                                --app app.py \
                                --mode standalone \
                                --jobs 8

Tests avant release

python -m pytest -v
                                python -m compileall .
                                python scripts/validate_artifact.py

Créer archive Linux

mkdir -p dist/releases

                                cd build/nuitka
                                zip -r ../../dist/releases/app-linux-x86_64-py312-standalone.zip app.dist
                                cd ../..

                                sha256sum dist/releases/*.zip > dist/releases/SHA256SUMS.txt

Créer archive Windows PowerShell

New-Item -ItemType Directory -Force dist\releases

                                Compress-Archive `
                                -Path build\nuitka\app.dist `
                                -DestinationPath dist\releases\app-windows-amd64-py312-standalone.zip `
                                -Force

                                Get-FileHash dist\releases\*.zip -Algorithm SHA256 |
                                Format-Table -AutoSize |
                                Out-File dist\releases\SHA256SUMS.txt

Top commandes

# Install
                                python -m venv .venv
                                source .venv/bin/activate
                                python -m pip install -U pip setuptools wheel
                                python -m pip install -U nuitka ordered-set zstandard

                                # Verify
                                python -m nuitka --version

                                # Simple build
                                python -m nuitka app.py

                                # Standalone
                                python -m nuitka --mode=standalone --assume-yes-for-downloads app.py

                                # Onefile
                                python -m nuitka --mode=onefile --assume-yes-for-downloads app.py

                                # Module
                                python -m nuitka --mode=module package/core_engine.py

Top options

# Output
                                --output-dir=build/nuitka
                                --remove-output
                                --show-progress
                                --show-memory
                                --report=build/reports/report.xml

                                # Data
                                --include-data-dir=templates=templates
                                --include-data-dir=static=static
                                --include-data-files=config.yaml=config.yaml
                                --include-data-files=rules/*.json=rules/

                                # Imports
                                --include-module=myapp.plugins.csv_exporter
                                --include-package=myapp.plugins

                                # Build comfort
                                --jobs=8
                                --assume-yes-for-downloads