Skip to content

Add PyInstaller hooks for pytz, lap, and PIL.ImageGrab runtime imports #383

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Copilot wants to merge 6 commits into
base: main
Choose a base branch
from
+1,020 −6
Draft

Add PyInstaller hooks for pytz, lap, and PIL.ImageGrab runtime imports #383

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
cc191e0
Initial plan
Copilot Jan 23, 2026
dab7771
Add PyInstaller hooks to fix pytz, lap, and PIL.ImageGrab imports in …
Copilot Jan 23, 2026
e1d72ec
Fix imports in spec files and add documentation for .exe build fixes
Copilot Jan 23, 2026
47f3e55
Add complete summary documentation for .exe import fixes
Copilot Jan 23, 2026
9072398
Address code review feedback: update shebangs to python3 and simplify…
Copilot Jan 23, 2026
3092eba
Add final mission complete summary for .exe import fixes
Copilot Jan 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 9 additions & 3 deletions CV_Studio.spec
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ The .exe will be created in the 'dist/CV_Studio' directory.

import os
import sys
from PyInstaller.utils.hooks import collect_data_files, collect_submodules
from PyInstaller.utils.hooks import collect_data_files, collect_submodules, collect_dynamic_libs

# Get the base directory
block_cipher = None
Expand Down Expand Up @@ -148,17 +148,23 @@ datas += collect_data_files('mediapipe')
datas += collect_data_files('onnxruntime')
datas += collect_data_files('librosa')
datas += collect_data_files('sklearn')
# Add pytz timezone data files (CRITICAL for pytz to work in .exe)
datas += collect_data_files('pytz')
# Add PIL/Pillow data files
datas += collect_data_files('PIL')

# Binary excludes - exclude unnecessary binaries
# Collect binaries for packages with compiled extensions
binaries = []
# Add lap compiled C extensions (CRITICAL for lap to work in .exe)
binaries += collect_dynamic_libs('lap')

a = Analysis(
['main.py'],
pathex=[base_path],
binaries=binaries,
datas=datas,
hiddenimports=hiddenimports,
hookspath=[],
hookspath=['hooks'], # Use custom hooks directory for pytz, lap, PIL fixes
hooksconfig={},
runtime_hooks=[],
excludes=[
Expand Down
170 changes: 170 additions & 0 deletions FIX_EXE_IMPORTS_EN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,170 @@
# Fix for Import Issues in .exe Executable

## Problem Solved

After building the .exe executable with PyInstaller, the following errors occurred:

1. **pytz** - `ModuleNotFoundError: No module named 'pytz'`
2. **lap** - `ModuleNotFoundError: No module named 'lap'` or runtime errors
3. **PIL.ImageGrab** - Errors when using screen capture functionality

## Root Cause

PyInstaller doesn't automatically detect certain special dependencies:

- **pytz**: Timezone data files are not automatically included
- **lap**: Compiled C extensions (.pyd/.so) are not detected
- **PIL.ImageGrab**: Requires explicit inclusion, especially on Windows

## Implemented Solution

### 1. Custom PyInstaller Hooks

Three hooks were created in the `hooks/` directory:

#### `hooks/hook-pytz.py`
Collects pytz timezone data files and all its submodules.

**Affected Node:** `node.ActionNode.node_mongodb` (uses pytz for UTC timezone handling)

#### `hooks/hook-lap.py`
Collects dynamic libraries (compiled C extensions) and submodules of lap.

**Affected Node:** `node.TrackerNode.mot.bytetrack.tracker.matching` (uses lap for object tracking)

#### `hooks/hook-PIL.py`
Ensures PIL.ImageGrab and all PIL dependencies are properly included.

**Affected Node:** `node.VideoNode.node_screen_capture` (uses PIL.ImageGrab for screen capture)

### 2. CV_Studio.spec Modifications

The following changes were made:

```python
# Add data files for pytz and PIL
datas += collect_data_files('pytz') # CRITICAL for pytz
datas += collect_data_files('PIL')

# Add compiled binaries for lap
from PyInstaller.utils.hooks import collect_dynamic_libs
binaries = []
binaries += collect_dynamic_libs('lap') # CRITICAL for lap

# Use hooks directory
a = Analysis(
...
hookspath=['hooks'], # Use custom hooks
...
)
```

### 3. build_exe.py Modifications

The same modifications were applied to the build script to ensure consistency.

## How to Use

### Standard Build
```bash
python build_exe.py --clean
```

### Build with PyInstaller Directly
```bash
pyinstaller CV_Studio.spec
```

### Test Critical Imports
```bash
python test_critical_imports.py
```

## Verification After Build

1. **Build the executable**
```bash
python build_exe.py --clean
```

2. **Run the exe**
```bash
cd dist/CV_Studio
CV_Studio.exe
```

3. **Test problematic nodes**
- MongoDB node (tests pytz)
- ByteTrack tracker node (tests lap)
- Screen Capture node (tests PIL.ImageGrab)

## Added File Structure

```
CV_Studio/
├── hooks/
│ ├── README.md # Hooks documentation
│ ├── hook-pytz.py # Hook for pytz
│ ├── hook-lap.py # Hook for lap
│ └── hook-PIL.py # Hook for PIL/Pillow
├── test_critical_imports.py # Import test script
├── CV_Studio.spec # Modified
└── build_exe.py # Modified
```

## Troubleshooting

### If imports still fail after build

1. **Clean and rebuild**
```bash
python build_exe.py --clean
```

2. **Check PyInstaller warnings**
During build, look for warnings about pytz, lap, or PIL

3. **Verify hooks directory exists**
```bash
ls -la hooks/
```

4. **Install all dependencies**
```bash
pip install -r requirements.txt
```

### Common Error Messages and Solutions

#### `ModuleNotFoundError: No module named 'pytz'`
- **Solution**: The pytz hook wasn't used. Verify that `hookspath=['hooks']` is in the spec.

#### `ModuleNotFoundError: No module named 'lap'` or runtime crash
- **Solution**: lap C extensions are not included. Check `collect_dynamic_libs('lap')`.

#### `ImportError: cannot import name 'ImageGrab'`
- **Solution**: PIL.ImageGrab is unavailable or misconfigured. Check the PIL hook.

## Technical References

- **PyInstaller Hooks**: https://pyinstaller.org/en/stable/hooks.html
- **pytz**: https://pypi.org/project/pytz/
- **lap**: https://pypi.org/project/lap/
- **Pillow**: https://pypi.org/project/Pillow/

## Changelog

### Current Version
- ✅ Added PyInstaller hooks for pytz, lap, and PIL
- ✅ Updated CV_Studio.spec with hookspath and data collections
- ✅ Updated build_exe.py for consistency
- ✅ Added test_critical_imports.py test script
- ✅ Complete documentation of fixes

## Support

If you still encounter issues after applying these fixes:

1. Run `python test_critical_imports.py` before building
2. Check PyInstaller warnings during build
3. Open a GitHub issue with complete error logs
170 changes: 170 additions & 0 deletions FIX_EXE_IMPORTS_FR.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,170 @@
# Fix pour les problèmes d'import dans l'exécutable .exe

## Problème résolu

Après avoir construit l'exécutable .exe avec PyInstaller, les erreurs suivantes se produisaient :

1. **pytz** - `ModuleNotFoundError: No module named 'pytz'`
2. **lap** - `ModuleNotFoundError: No module named 'lap'` ou erreur lors de l'utilisation
3. **PIL.ImageGrab** - Erreurs lors de l'utilisation de la capture d'écran

## Cause du problème

PyInstaller ne détecte pas automatiquement certaines dépendances spéciales :

- **pytz** : Les fichiers de données de timezone ne sont pas inclus automatiquement
- **lap** : Les extensions C compilées (.pyd/.so) ne sont pas détectées
- **PIL.ImageGrab** : Nécessite une inclusion explicite, surtout sur Windows

## Solution implémentée

### 1. Hooks PyInstaller personnalisés

Trois hooks ont été créés dans le répertoire `hooks/` :

#### `hooks/hook-pytz.py`
Collecte les fichiers de données de timezone de pytz et tous ses sous-modules.

**Node affecté :** `node.ActionNode.node_mongodb` (utilise pytz pour la gestion des fuseaux horaires UTC)

#### `hooks/hook-lap.py`
Collecte les bibliothèques dynamiques (extensions C compilées) et les sous-modules de lap.

**Node affecté :** `node.TrackerNode.mot.bytetrack.tracker.matching` (utilise lap pour le tracking d'objets)

#### `hooks/hook-PIL.py`
Assure que PIL.ImageGrab et toutes les dépendances PIL sont correctement incluses.

**Node affecté :** `node.VideoNode.node_screen_capture` (utilise PIL.ImageGrab pour la capture d'écran)

### 2. Modifications de CV_Studio.spec

Les modifications suivantes ont été apportées :

```python
# Ajout des fichiers de données pour pytz et PIL
datas += collect_data_files('pytz') # CRITICAL pour pytz
datas += collect_data_files('PIL')

# Ajout des binaires compilés pour lap
from PyInstaller.utils.hooks import collect_dynamic_libs
binaries = []
binaries += collect_dynamic_libs('lap') # CRITICAL pour lap

# Utilisation du répertoire hooks
a = Analysis(
...
hookspath=['hooks'], # Utilise les hooks personnalisés
...
)
```

### 3. Modifications de build_exe.py

Les mêmes modifications ont été appliquées au script de build pour garantir la cohérence.

## Comment utiliser

### Build standard
```bash
python build_exe.py --clean
```

### Build avec PyInstaller directement
```bash
pyinstaller CV_Studio.spec
```

### Tester les imports critiques
```bash
python test_critical_imports.py
```

## Vérification après build

1. **Construire l'exécutable**
```bash
python build_exe.py --clean
```

2. **Exécuter l'exe**
```bash
cd dist/CV_Studio
CV_Studio.exe
```

3. **Tester les nodes problématiques**
- Node MongoDB (teste pytz)
- Node ByteTrack tracker (teste lap)
- Node Screen Capture (teste PIL.ImageGrab)

## Structure des fichiers ajoutés

```
CV_Studio/
├── hooks/
│ ├── README.md # Documentation des hooks
│ ├── hook-pytz.py # Hook pour pytz
│ ├── hook-lap.py # Hook pour lap
│ └── hook-PIL.py # Hook pour PIL/Pillow
├── test_critical_imports.py # Script de test des imports
├── CV_Studio.spec # Modifié
└── build_exe.py # Modifié
```

## Dépannage

### Si les imports échouent encore après le build

1. **Nettoyer et reconstruire**
```bash
python build_exe.py --clean
```

2. **Vérifier les warnings de PyInstaller**
Pendant le build, cherchez des avertissements concernant pytz, lap ou PIL

3. **Vérifier que le répertoire hooks existe**
```bash
ls -la hooks/
```

4. **Installer toutes les dépendances**
```bash
pip install -r requirements.txt
```

### Messages d'erreur courants et solutions

#### `ModuleNotFoundError: No module named 'pytz'`
- **Solution** : Le hook pytz n'a pas été utilisé. Vérifiez que `hookspath=['hooks']` est dans le spec.

#### `ModuleNotFoundError: No module named 'lap'` ou crash au runtime
- **Solution** : Les extensions C de lap ne sont pas incluses. Vérifiez `collect_dynamic_libs('lap')`.

#### `ImportError: cannot import name 'ImageGrab'`
- **Solution** : PIL.ImageGrab n'est pas disponible ou mal configuré. Vérifiez le hook PIL.

## Références techniques

- **PyInstaller Hooks** : https://pyinstaller.org/en/stable/hooks.html
- **pytz** : https://pypi.org/project/pytz/
- **lap** : https://pypi.org/project/lap/
- **Pillow** : https://pypi.org/project/Pillow/

## Changelog

### Version actuelle
- ✅ Ajout de hooks PyInstaller pour pytz, lap, et PIL
- ✅ Mise à jour de CV_Studio.spec avec hookspath et collections de données
- ✅ Mise à jour de build_exe.py pour cohérence
- ✅ Ajout de script de test test_critical_imports.py
- ✅ Documentation complète des fixes

## Support

Si vous rencontrez toujours des problèmes après avoir appliqué ces fixes :

1. Exécutez `python test_critical_imports.py` avant le build
2. Vérifiez les warnings PyInstaller pendant le build
3. Ouvrez une issue sur GitHub avec les logs d'erreur complets
Loading