Build from Source

🛠 Build from Source

Want to build the EXE yourself, contribute to the code, or customize the app? This guide walks you through every step.

💡 Just want to use the app? Skip this and download the ready-made EXE from the Releases page.

---

✅ Prerequisites

	Requirement
🐍	Python 3.8 or newer — python.org
🪟	Windows 10 / 11 (64-bit)
📦	Git — git-scm.com
💻	VS Code (recommended) or any code editor

Verify Python is installed

python --version

Should output something like Python 3.11.5.

---

📥 Step 1 — Clone the Repository

git clone https://github.com/ZvanTors/GoodByeDPI-GUI.git
cd GoodByeDPI-GUI

---

📦 Step 2 — Install Dependencies

Option A — From requirements file (recommended):

pip install -r requirements.txt

Option B — Manually:

pip install pyside6 pyinstaller

💡 Using a virtual environment is recommended:

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

---

📁 Step 3 — Add GoodbyeDPI Binaries

The GUI doesn't ship the engine — you need to provide it. Download the latest GoodbyeDPI release and place these three files inside the bin/ folder:

File	Source
bin/goodbyedpi.exe	From GoodbyeDPI release
bin/WinDivert.dll	From GoodbyeDPI release (x86_64 folder)
bin/WinDivert64.sys	From GoodbyeDPI release (x86_64 folder)

Final structure should look like:

GoodByeDPI-GUI/
├── main.py
├── requirements.txt
├── assets/
│   └── logo.ico
├── bin/
│   ├── goodbyedpi.exe
│   ├── WinDivert.dll
│   └── WinDivert64.sys
└── app/
    └── ...

⚠️ Make sure you use the 64-bit versions of the DLL and SYS files.

---

🎨 Step 4 — Add an Icon (optional)

If you want a custom icon, place logo.ico inside the assets/ folder.

If you don't have one, skip this step — the app will run fine without it.

---

🧪 Step 5 — Test Before Building

Always run the app from source first to catch errors early:

python main.py

Run it as Administrator — the app requires it and will refuse to start otherwise.

💡 Tip: In VS Code, open a Terminal (Ctrl+`) and make sure it's running as admin, or use an elevated PowerShell window.

If everything works (window opens, mode cards appear, Start button works), you're ready to build.

---

🏗 Step 6 — Build the EXE

One-line command (CMD)

pyinstaller --onefile --windowed --uac-admin --name "GoodByeDPI GUI" --add-data "assets;assets" --add-data "bin;bin" --icon=assets/logo.ico main.py

Multi-line command (CMD — with ^)

pyinstaller --onefile --windowed --uac-admin --name "GoodByeDPI GUI" ^
  --add-data "assets;assets" ^
  --add-data "bin;bin" ^
  --icon=assets/logo.ico ^
  main.py

Multi-line command (PowerShell — with backtick)

pyinstaller --onefile --windowed --uac-admin --name "GoodByeDPI GUI" `
  --add-data "assets;assets" `
  --add-data "bin;bin" `
  --icon=assets/logo.ico `
  main.py

What each flag does

Flag	Purpose
--onefile	Bundle everything into a single EXE
--windowed	Hide the console window
--uac-admin	Request admin privileges on launch
--name	Name of the output EXE
--add-data	Include assets/ and bin/ folders
--icon	Set the EXE icon

⚠️ On Windows, the separator in --add-data is ; — not :. Using : will silently fail.

---

📦 Step 7 — Find Your EXE

After the build completes, PyInstaller creates a dist/ folder:

dist/
└── GoodByeDPI GUI.exe

Rename it to match the release convention used by the updater:

dist/GoodByeDPI.GUI.exe

💡 This name matters — the in-app updater looks for exactly GoodByeDPI.GUI.exe in GitHub releases.

---

🚀 Step 8 — Test the Built EXE

1. Move the EXE to a different folder (e.g., Desktop) to test portability
2. Right-click → Run as administrator
3. Verify:
   • ✅ Window opens
   • ✅ Icons and theme render correctly
   • ✅ Mode cards appear
   • ✅ Start/Stop works
   • ✅ Toasts appear at bottom-right

---

🧹 Step 9 — Clean Up (optional)

After a successful build, you can safely delete:

build/
*.spec

Only dist/ and your source files matter.

---

🔁 Rebuilding After Changes

Whenever you modify the source, just run the build command again. PyInstaller overwrites the old EXE.

💡 To keep builds clean, delete build/ and dist/ first:

rmdir /s /q build dist

---

🩺 Troubleshooting the Build

❌ pyinstaller: command not found

PyInstaller isn't installed or isn't on your PATH.

pip install pyinstaller
python -m PyInstaller --version

If that works, use python -m PyInstaller instead of pyinstaller.

❌ ModuleNotFoundError: No module named 'app'

You're building from the wrong directory. Make sure you're in the project root:

cd GoodByeDPI-GUI
pyinstaller ...

❌ Assets or binaries missing in the EXE

Check your --add-data flags. The separator must be ; on Windows.

Also verify the source folders actually exist:

dir assets
dir bin

❌ EXE opens then closes immediately

Run it from CMD to see the error:

"dist\GoodByeDPI.GUI.exe"

Common causes:

• Missing bin/goodbyedpi.exe
• Not running as admin
• Antivirus quarantined a bundled file

❌ Antivirus flags the built EXE

PyInstaller EXEs are sometimes flagged as suspicious — a known false positive. Add the folder to your antivirus exclusions.

❌ Build takes forever

Normal — first build can take 1-3 minutes. Subsequent builds are faster.

---

💡 Pro Tips

• 🎯 Use a virtual environment — avoids polluting your global Python install
• 🧹 Clean before rebuild — deletes stale artifacts
• 📏 Check EXE size — a healthy build is ~40-60 MB
• 🔒 Sign your EXE (optional) — reduces antivirus false positives (requires a code-signing certificate)
• 📝 Version your build — bump APP_VERSION in app/constants.py before release

---

Next: Understand the codebase in Architecture 🏗