Frequently Asked Questions
Problems with running frozen programs
A common problem is that cx_Freeze hasn’t automatically detected that a file needs to be copied. Modules that your code imports are detected, but if they’re dynamically loaded - e.g. by a plugin system - you have to tell cx_Freeze about them. This is easy using a setup script:
For Python code, specify the module names in the
List the module’s compiled libraries (.dll or .so files) in the
bin_includesto include dependencies of binary files that would normally be excluded (a common use is to include “libffi.so”).
Data files are a bit more complex - see Using data files.
Problems with freezing programs
To determine which packages need to be copied with your application,
cx_Freeze follows the imports. If your installation contains a lot of
packages, this may lead to undesired behavior, such as cx_Freeze
encountering a recursion error when trying to compute the list of dependencies,
or the lib folder of the frozen application containing many unnecessary
In this case, you may want to use cx_Freeze in a virtualenv. Alternatively, the
setup_script also offers the
excludes option to explicitly exclude
dependencies which would otherwise be included.
Specifying modules and packages
The definitions of modules and packages are different. See python documentation.
Windows command prompt appears briefly
If there’s a problem with your frozen application, you may see a command prompt window appear briefly when you try to run it, and then disappear again. This happens when a console-mode executable exits quickly, usually if there’s an error as soon as it starts.
There are two ways to debug what’s going on:
Freeze your application with the
Win32GUIbase (see setup script or cxfreeze script). This doesn’t use a console window, and reports errors in a dialog box.
Alternatively, start a command prompt yourself and launch the frozen executable from the command line. This will let you see any error messages in the console.
Freezing for other platforms
cx_Freeze works on Windows, Mac and Linux, but on each platform it only makes an executable that runs on that platform. So if you want to freeze your programs for Windows, freeze it on Windows; if you want to run it on Macs, freeze it on a Mac.
At a pinch, you can try to make a Windows executable using Wine. Our experience is that you need to copy some files in manually after cx_Freeze has run to make the executable work. We don’t recommend this option.
Using data files
Applications often need data files besides the code, such as icons. Using a
setup script, you can list data files or directories in the
include_files option to
build_exe. They’ll be copied to the build
directory alongside the executable. Then to find them, use code like this:
def find_data_file(filename): if getattr(sys, "frozen", False): # The application is frozen datadir = os.path.dirname(sys.executable) else: # The application is not frozen # Change this bit to match where you store your data files: datadir = os.path.dirname(__file__) return os.path.join(datadir, filename)
An alternative is to embed data in code, for example by using Qt’s resource system.
Microsoft Visual C++ Redistributable Package
Python 3.6-3.10 on Windows requires the Visual C++ Redistributable for Visual Studio 2015, 2017 or 2019 (the redistributables are shared), and because of how this is installed, cx_Freeze doesn’t automatically copy it for your application.
You’re responsible for checking the license conditions associated with the DLLs you have installed.
If your license allows you to distribute these files, specify the
include_msvcroption to build_exe to have them distributed automatically.
If not, your users or your installer will need to install the Microsoft Visual C++ Redistributable Package (a free download from Microsoft). It’s not uncommon for this to already be present on modern computers, but it’s not, as far as we know, part of a standard Windows installation.
cx_Freeze does not support building a single file exe, where all of the libraries for your application are embedded in one executable file.
You can use other tools to compress the build directory from cx_Freeze into a self-extracting archive: