Turn Your Python Script into a Windows EXE — Complete Beginner-Friendly Guide

You’ve built your Python project, tested it, everything works perfectly. Now it’s time to share it… but the other person doesn’t have Python installed, no libraries, different system setup. At this point we all face the same question: “How do I turn this into a simple double-click app?”

In this guide, we’ll walk through converting a Python script into a Windows .exe step by step. Whether it’s your first time trying or you’ve already experimented with packaging before, you’ll find clear explanations on everything from commands and folder structure to adding icons and handling common errors.

The goal is simple: if you can write Python code but packaging feels confusing, these steps will help you turn your script into something anyone can run easily. Ready? Let’s start.

0) Quick preparation check

Goal: make sure Python exists on your system.

1. Open PowerShell (Start → type “PowerShell” → open).
2. Check Python:

> python --version

If you don’t see something like Python 3.x.x, install Python from https://python.org first.

1) Put your project in a folder

Example project folder:

C:\Users\You\Projects\MyApp

Go there in PowerShell:

> cd C:\Users\You\Projects\MyApp

You should have a main script, e.g. main.py.

Quick test script if you need one:

# main.py
print("App started")
input("Press Enter to exit")

2) Create a virtual environment (recommended)

Keeps your dependencies clean:

> python -m venv venv

Activate it:

> .\venv\Scripts\Activate.ps1

If PowerShell complains about script permission:

> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
> .\venv\Scripts\Activate.ps1

Update pip:

(venv) > python -m pip install --upgrade pip

3) Install PyInstaller

(venv) > pip install pyinstaller

(Optional check)

(venv) > pyinstaller --version

4) Create the .exe — simplest command

(venv) > pyinstaller --onefile main.py

When it finishes, check:

dist\main.exe

Test it:

> .\dist\main.exe

5) Give it a name, icon, hide console (for GUI apps)

(venv) > pyinstaller --onefile --name "MyApp" --icon "app.ico" --noconsole main.py

Notes:

• .ico only — not .png
• Do not use --noconsole if it’s a command-line tool (you’ll lose error messages)

6) If your program uses extra files (images, config, etc.)

Example with a config file:

(venv) > pyinstaller --onefile --add-data "data\config.json;data" main.py

Windows uses ; — macOS/Linux uses :.

7) Fix file paths inside the exe

PyInstaller packages files differently. Use this to load files safely:

import sys, os

if getattr(sys, 'frozen', False):
    base_path = sys._MEIPASS
else:
    base_path = os.path.dirname(__file__)

config_path = os.path.join(base_path, 'data', 'config.json')

8) --onefile vs --onedir

Mode	What it does	When to use
--onefile	One single exe	Easy sharing, small app
--onedir	Folder with exe + DLLs	Fewer antivirus issues, easier debugging

Example:

(venv) > pyinstaller --onedir --name "MyApp" main.py

9) Fixed missing imports

If exe complains about missing modules:

(venv) > pyinstaller --onefile --hidden-import module_name main.py

Or collect everything automatically:

(venv) > pyinstaller --onefile --collect-all module_name main.py

10) Debugging

(venv) > pyinstaller --onefile --log-level=DEBUG main.py

Check build folder for warnings logs.

11) Antivirus warnings

Unfortunately very common for Python exes — especially --onefile.

Solutions:

• Try --onedir
• Zip the files before sharing
• Sign your executable (for professional apps)

12) GUI frameworks tips

• Tkinter → usually works smoothly
• PyQt / PySide → may need --add-data for plugins/DLLs
• Kivy → check their packaging docs; heavier apps

13) Clean build folders

> rmdir /s /q build dist
> del *.spec

Zip output for sharing:

> Compress-Archive -Path .\dist\MyApp.exe -DestinationPath .\MyApp.zip

14) Quick fixes cheat list

Problem	Fix
EXE won’t open	--onenir, run with --log-level=DEBUG
Files not found	Add --add-data + use sys._MEIPASS in code
Icon not working	Must be .ico
Antivirus flags	Prefer --onedir, sign exe later

15) Shortest possible workflow (copy-paste)

> python -m venv venv
> .\venv\Scripts\Activate.ps1
(venv) > pip install --upgrade pip
(venv) > pip install pyinstaller
(venv) > pyinstaller --onefile --name "MyApp" main.py
> .\dist\MyApp.exe