Install PyInstaller in your project’s Python environment, open Command Prompt in the folder containing your script, and run pyinstaller your_program.py. This creates a Windows executable and, by default, places it with its supporting files in a dist folder. Build a Windows app on Windows: PyInstaller does not cross-compile.
Build your first executable
-
Open the Python environment used by your project, then install or update PyInstaller with
pip install -U pyinstaller. The PyInstaller manual documents installation and use. -
Open Command Prompt and change to the directory containing your script. For example, if the file is named
your_program.py, run:pyinstaller your_program.py -
When the command finishes, look in
distfor the packaged application. The default build is a folder containing the executable and its dependencies.Recommended Free Tools
Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy. -
Run the executable and test the workflows your script needs, including any files it reads or writes. A successful build command alone does not establish that the packaged program works correctly.
Choose one-folder or one-file output
Get the default one-folder build working first. The PyInstaller manual describes it as easier to debug because the collected files are visible; switch to one-file only if handing off a single executable is more useful than that visibility.
| Mode | What you distribute | Practical trade-off |
|---|---|---|
--onedir (default) |
An application folder containing the executable and supporting files. | Collected files are visible, which makes missing-file problems easier to diagnose. |
--onefile |
A single executable, with support files extracted to a temporary _MEI... directory when it starts. |
Startup is slower because of extraction. Related items such as a README still need to be distributed separately. |
To make the one-file build, use pyinstaller --onefile your_program.py. These layout and startup trade-offs are described in the PyInstaller operating modes documentation.
Package a Windows GUI app
For a GUI program that should not show a console window, use --windowed (also called --noconsole), for example pyinstaller --windowed your_program.py. Keep the console enabled while debugging so errors remain visible. The usage documentation also describes options for Windows version resources and manifests when you need application metadata or a manifest.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Fix missing imports and files
Imports PyInstaller cannot detect
PyInstaller analyzes imports, but runtime-selected imports may not be apparent during analysis. This can happen with calls such as __import__() using variable data, importlib.import_module(), or runtime changes to sys.path. If an import works in your source environment but is missing in the packaged app, investigate hidden imports, additional search paths, hooks, and the generated .spec file. A hook can specify how PyInstaller should collect a package. See the manual’s troubleshooting guidance.
Data files and binaries
Do not assume resources used by your script will automatically be included in the bundle. Add required data files with the data-file command-line option or configure them in the spec file; the spec can also describe binaries that analysis missed. A spec file is executable Python configuration, so build only from one you trust. The spec-file documentation explains how to configure collected files.
Resource paths at runtime
Paths that work in your source tree may not work after freezing. PyInstaller sets sys.frozen and sys._MEIPASS; sys._MEIPASS points inside the one-folder bundle or to the temporary extraction directory in one-file mode. sys.executable identifies the executable the user launched, while sys.argv[0] can be relative or depend on how the app was launched. Use these documented attributes when locating resources or launching subprocesses instead of assuming the current working directory is your source folder. Details are in the manual’s runtime information section.
Build for the target operating system
PyInstaller is not a cross-compiler: build a Windows executable on Windows, a Linux application on Linux, and a macOS application on macOS. The manual identifies Windows, macOS, and Linux as tested platforms. It notes successful use on some other operating systems but does not provide CI testing or guarantees for them. See the platform and installation information in the manual.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsPyInstaller bundles the active Python interpreter and detected dependencies, so end users generally do not need to install Python separately. It does not bundle system libraries that the target operating system is expected to provide. When practical, test on a clean machine matching the target system, particularly if the program uses native libraries.
For one-file builds, the manual also notes that file attributes are not preserved. If executable permissions or other metadata matter for files in your package, check those properties in the delivered build.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
