Skip to content

Commit 30e5054

Browse files
mauriciomenonmauriciomenon
committed
fix Windows installation instructions and requirements
- fix requirements.txt formatting (remove extra blank line) - update README.md with proper Windows virtual environment activation - create comprehensive INSTALL_WINDOWS.md guide for Windows users - improve BUILD_WINDOWS_NATIVE.md with detailed troubleshooting - add platform-specific command examples and paths Windows users now have complete step-by-step installation guide
1 parent ef6f032 commit 30e5054

3 files changed

Lines changed: 216 additions & 15 deletions

File tree

‎BUILD_WINDOWS_NATIVE.md‎

Lines changed: 50 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,58 @@
11
# Building Native Windows Executable
22

33
## Requirements
4-
- Windows 10/11 (AMD64)
5-
- Python 3.8+ installed
6-
- Git for Windows (optional)
4+
- Windows 10/11 (AMD64/x86_64)
5+
- Python 3.8+ installed from [python.org](https://www.python.org/downloads/)
6+
- Git for Windows (optional) from [git-scm.com](https://git-scm.com/)
77

88
## Setup on Windows
99

10+
### Method 1: Using Git
1011
1. **Clone repository:**
1112
```cmd
1213
git clone https://github.com/yourusername/ffmpeg-gui-pyqt6.git
1314
cd ffmpeg-gui-pyqt6
1415
```
1516

16-
2. **Create virtual environment:**
17+
### Method 2: Download ZIP
18+
1. **Download repository:**
19+
- Go to GitHub repository page
20+
- Click "Code" > "Download ZIP"
21+
- Extract to desired folder
22+
- Open Command Prompt in extracted folder
23+
24+
### Setup Virtual Environment
25+
2. **Create and activate virtual environment:**
1726
```cmd
1827
python -m venv .venv
19-
.venv\Scripts\activate
28+
.venv\Scripts\activate.bat
2029
```
30+
31+
**Note:** If you see `(.venv)` at the start of your command prompt, the virtual environment is active.
2132

2233
3. **Install dependencies:**
2334
```cmd
35+
pip install --upgrade pip
2436
pip install -r requirements.txt
2537
```
2638

39+
### Test Installation
40+
4. **Test the application:**
41+
```cmd
42+
python GUI_pyqt6_WINFF.py
43+
```
44+
2745
## Build Native Windows .exe
2846

2947
### Method 1: Using spec file (recommended)
3048
```cmd
31-
.venv\Scripts\activate
49+
.venv\Scripts\activate.bat
3250
pyinstaller FFmpeg_GUI_Windows.spec
3351
```
3452

3553
### Method 2: Direct command
3654
```cmd
37-
.venv\Scripts\activate
55+
.venv\Scripts\activate.bat
3856
pyinstaller --onefile --windowed --name=FFmpeg_GUI_Windows_AMD64 ^
3957
--add-data="utils_safe_extract.py;." ^
4058
--hidden-import=PyQt6.QtCore ^
@@ -48,17 +66,37 @@ pyinstaller --onefile --windowed --name=FFmpeg_GUI_Windows_AMD64 ^
4866
```
4967

5068
## Output
51-
- Executable: `dist\FFmpeg_GUI_Windows_AMD64.exe`
52-
- Size: ~40-60MB (native Windows)
53-
- Format: PE32+ executable (Windows .exe)
69+
- **Executable**: `dist\FFmpeg_GUI_Windows_AMD64.exe`
70+
- **Size**: ~40-60MB (native Windows)
71+
- **Format**: PE32+ executable (Windows .exe)
5472

5573
## Testing
5674
```cmd
5775
dist\FFmpeg_GUI_Windows_AMD64.exe
5876
```
5977

78+
## Troubleshooting
79+
80+
### "python is not recognized"
81+
- Install Python from [python.org](https://www.python.org/downloads/)
82+
- Check "Add Python to PATH" during installation
83+
- Restart Command Prompt after installation
84+
85+
### "No module named PyQt6"
86+
- Ensure virtual environment is activated: `.venv\Scripts\activate.bat`
87+
- Install requirements: `pip install -r requirements.txt`
88+
89+
### "Permission denied" errors
90+
- Run Command Prompt as Administrator
91+
- Check antivirus software (may block PyInstaller)
92+
93+
### Build fails with missing modules
94+
- Add missing modules to `hidden-import` list in spec file
95+
- Check PyInstaller warnings in build output
96+
6097
## Notes
61-
- This creates a true Windows .exe file
98+
- Creates a true Windows .exe file (PE32+ format)
6299
- No Wine or compatibility layer needed
63-
- Smaller size than cross-compiled version
100+
- Smaller size than cross-compiled version
64101
- Better Windows integration (file associations, etc.)
102+
- Works on Windows 10/11 AMD64 systems

‎INSTALL_WINDOWS.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# Windows Installation Guide
2+
3+
## Quick Start for Windows Users
4+
5+
### Prerequisites
6+
1. **Download Python 3.8+** from [python.org](https://www.python.org/downloads/)
7+
- ✅ **IMPORTANT**: Check "Add Python to PATH" during installation
8+
- Choose "Custom Installation" > Check "Add Python to environment variables"
9+
10+
2. **Verify Python Installation:**
11+
```cmd
12+
python --version
13+
pip --version
14+
```
15+
16+
### Option 1: Download Repository as ZIP
17+
1. Go to the [GitHub repository](https://github.com/yourusername/ffmpeg-gui-pyqt6)
18+
2. Click green "Code" button > "Download ZIP"
19+
3. Extract ZIP to a folder (e.g., `C:\ffmpeg-gui`)
20+
4. Open Command Prompt and navigate to the folder:
21+
```cmd
22+
cd C:\ffmpeg-gui
23+
```
24+
25+
### Option 2: Using Git (if installed)
26+
```cmd
27+
git clone https://github.com/yourusername/ffmpeg-gui-pyqt6.git
28+
cd ffmpeg-gui-pyqt6
29+
```
30+
31+
## Setup and Run
32+
33+
### 1. Create Virtual Environment
34+
```cmd
35+
python -m venv .venv
36+
```
37+
38+
### 2. Activate Virtual Environment
39+
```cmd
40+
.venv\Scripts\activate.bat
41+
```
42+
**Note:** You should see `(.venv)` at the beginning of your command prompt
43+
44+
### 3. Install Dependencies
45+
```cmd
46+
pip install --upgrade pip
47+
pip install PyQt6 ffmpeg-python pytest pyinstaller
48+
```
49+
50+
**Or use requirements file:**
51+
```cmd
52+
pip install -r requirements.txt
53+
```
54+
55+
### 4. Run the Application
56+
```cmd
57+
python GUI_pyqt6_WINFF.py
58+
```
59+
60+
## Creating Windows Executable
61+
62+
If you want to create a standalone .exe file:
63+
64+
### 1. Install PyInstaller (if not already installed)
65+
```cmd
66+
pip install pyinstaller
67+
```
68+
69+
### 2. Build executable
70+
```cmd
71+
pyinstaller --onefile --windowed --name=FFmpeg_GUI_Windows ^
72+
--add-data="utils_safe_extract.py;." ^
73+
--hidden-import=PyQt6.QtCore ^
74+
--hidden-import=PyQt6.QtGui ^
75+
--hidden-import=PyQt6.QtWidgets ^
76+
--hidden-import=ffmpeg ^
77+
GUI_pyqt6_WINFF.py
78+
```
79+
80+
### 3. Find your executable
81+
The .exe file will be created in: `dist\FFmpeg_GUI_Windows.exe`
82+
83+
## Troubleshooting
84+
85+
### "python is not recognized as an internal or external command"
86+
**Solution:** Python is not in your PATH
87+
1. Reinstall Python from [python.org](https://www.python.org/downloads/)
88+
2. **MUST CHECK**: "Add Python to PATH" during installation
89+
3. Restart Command Prompt
90+
91+
### "No module named 'PyQt6'"
92+
**Solution:** Virtual environment not activated or dependencies not installed
93+
1. Activate virtual environment: `.venv\Scripts\activate.bat`
94+
2. Install dependencies: `pip install -r requirements.txt`
95+
96+
### "Access is denied" when running activate.bat
97+
**Solution:** Execution policy restriction
98+
1. Run PowerShell as Administrator
99+
2. Run: `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`
100+
3. Try again with Command Prompt
101+
102+
### PyInstaller build fails
103+
**Solution:** Missing modules or antivirus interference
104+
1. Check antivirus software (may block PyInstaller)
105+
2. Add `--debug` to PyInstaller command to see detailed error
106+
3. Add missing modules with `--hidden-import=module_name`
107+
108+
### Application runs but can't find FFmpeg
109+
**Solution:** Use the built-in FFmpeg downloader
110+
1. Run the application
111+
2. Click "Baixar FFmpeg" button
112+
3. Or install FFmpeg separately and add to PATH
113+
114+
## Alternative: PowerShell Commands
115+
116+
If Command Prompt doesn't work, try PowerShell:
117+
118+
```powershell
119+
# Navigate to project folder
120+
cd C:\path\to\ffmpeg-gui-pyqt6
121+
122+
# Create virtual environment
123+
python -m venv .venv
124+
125+
# Activate (PowerShell syntax)
126+
.venv\Scripts\Activate.ps1
127+
128+
# Install and run
129+
pip install -r requirements.txt
130+
python GUI_pyqt6_WINFF.py
131+
```
132+
133+
## System Requirements
134+
135+
- **OS**: Windows 10 or Windows 11
136+
- **Architecture**: x64 (AMD64) - most modern PCs
137+
- **Python**: 3.8 or higher
138+
- **RAM**: 2GB minimum, 4GB recommended
139+
- **Disk Space**: 500MB for Python + dependencies
140+
141+
## Getting Help
142+
143+
1. Check this troubleshooting section first
144+
2. Ensure Python and pip are working: `python --version` and `pip --version`
145+
3. Make sure virtual environment is activated (look for `(.venv)` in prompt)
146+
4. Try running without virtual environment as a test
147+
5. Check Windows Event Viewer for application errors

‎README.md‎

Lines changed: 19 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -35,21 +35,37 @@ A graphical user interface for FFmpeg video conversion with both PyQt6 and Tkint
3535
```
3636

3737
2. **Set up virtual environment:**
38+
39+
**Windows:** See detailed guide in [INSTALL_WINDOWS.md](INSTALL_WINDOWS.md)
40+
```cmd
41+
python -m venv .venv
42+
.venv\Scripts\activate.bat
43+
```
44+
45+
**macOS/Linux:**
3846
```bash
3947
python3 -m venv .venv
40-
source .venv/bin/activate # On Windows: .venv\Scripts\activate
48+
source .venv/bin/activate
4149
```
4250

4351
3. **Install dependencies:**
4452
```bash
53+
# All platforms
4554
pip install -r requirements.txt
4655
```
4756

4857
4. **Run the application:**
49-
```bash
50-
# PyQt6 version
58+
59+
**Windows:**
60+
```cmd
5161
python GUI_pyqt6_WINFF.py
62+
rem Or Tkinter version
63+
python GUI_tkinter_WINFF.py
64+
```
5265

66+
**macOS/Linux:**
67+
```bash
68+
python GUI_pyqt6_WINFF.py
5369
# Or Tkinter version
5470
python GUI_tkinter_WINFF.py
5571
```

0 commit comments

Comments
 (0)