0
# cx_Freeze
1

2
A cross-platform Python package that creates standalone executables from Python scripts, maintaining the same performance as the original script. cx_Freeze provides a comprehensive build system for packaging Python applications into distributable executables for Windows, macOS, and Linux platforms.
3

4
## Package Information
5

6
- **Package Name**: cx_Freeze
7
- **Language**: Python
8
- **Installation**: `pip install cx_Freeze`
9

10
## Core Imports
11

12
```python
13
import cx_Freeze
14
from cx_Freeze import setup, Executable
15
```
16

17
For specific functionality:
18

19
```python
20
from cx_Freeze import (
21
    setup, Executable, Freezer, ConstantsModule,
22
    build_exe, ModuleFinder, Module, __version__
23
)
24
```
25

26
## Basic Usage
27

28
```python
29
from cx_Freeze import setup, Executable
30

31
# Define executable to create
32
executables = [
33
    Executable("main.py", base="console")
34
]
35

36
# Setup configuration
37
setup(
38
    name="MyApp",
39
    version="1.0",
40
    description="My Application",
41
    executables=executables,
42
    options={
43
        "build_exe": {
44
            "packages": ["tkinter"],
45
            "excludes": ["unittest"],
46
            "include_files": ["data/"]
47
        }
48
    }
49
)
50
```
51

52
Command-line usage:
53

54
```bash
55
# Basic freezing
56
cxfreeze --script main.py --target-dir dist
57

58
# With options
59
cxfreeze --script main.py --base gui --icon app.ico --target-dir dist
60

61
# Using setup.py
62
python setup.py build_exe
63

64
# Create MSI installer (Windows)
65
python setup.py bdist_msi
66
```
67

68
## Architecture
69

70
cx_Freeze operates through several key components:
71

72
- **Freezer**: Core freezing engine that analyzes dependencies and creates executables
73
- **ModuleFinder**: Discovers required modules through import analysis
74
- **Executable**: Represents an executable configuration with scripts, icons, and metadata
75
- **Commands**: Build and distribution commands for different platforms
76
- **Hooks**: Package-specific customizations for popular libraries
77
- **Base Executables**: Platform-specific executable templates (console, gui, service)
78

79
The freezing process works by:
80
1. Analyzing the main script and discovering all imported modules
81
2. Collecting Python modules, shared libraries, and data files
82
3. Creating a base executable that embeds the Python interpreter
83
4. Packaging everything into a distributable directory or installer
84

85
## Capabilities
86

87
### Core Executable Creation
88

89
The fundamental capability for defining and creating executable files from Python scripts, with support for different base types, icons, and metadata configuration.
90

91
```python { .api }
92
class Executable:
93
    def __init__(
94
        self,
95
        script: str | Path,
96
        init_script: str | Path | None = None,
97
        base: str | Path | None = None,
98
        target_name: str | None = None,
99
        icon: str | Path | None = None,
100
        shortcut_name: str | None = None,
101
        shortcut_dir: str | Path | None = None,
102
        copyright: str | None = None,
103
        trademarks: str | None = None,
104
        manifest: str | Path | None = None,
105
        uac_admin: bool = False,
106
        uac_uiaccess: bool = False,
107
    )
108

109
def setup(**attrs) -> setuptools.Distribution
110
```
111

112
[Executable Configuration](./executable-config.md)
113

114
### Build System Integration
115

116
Setuptools-compatible build commands for creating executables and managing the freezing process with extensive configuration options.
117

118
```python { .api }
119
class build_exe(Command):
120
    def initialize_options(self) -> None
121
    def finalize_options(self) -> None
122
    def run(self) -> None
123
```
124

125
[Build Commands](./build-commands.md)
126

127
### Installation Commands
128

129
Installation commands for deploying built executables and managing the installation process with customizable directory options.
130

131
```python { .api }
132
class install(Command):
133
    """Install everything from build directory."""
134

135
class install_exe(Command):
136
    """Install executables built from Python scripts."""
137
```
138

139
### Platform-Specific Distribution
140

141
Creation of platform-native installers and packages including MSI files for Windows, DMG and app bundles for macOS, and AppImages, DEBs, and RPMs for Linux.
142

143
```python { .api }
144
# Windows
145
class bdist_msi(Command): ...
146

147
# macOS  
148
class bdist_dmg(Command): ...
149
class bdist_mac(Command): ...
150

151
# Linux
152
class bdist_appimage(Command): ...
153
class bdist_deb(Command): ...
154
class bdist_rpm(Command): ...
155
```
156

157
[Distribution Commands](./distribution-commands.md)
158

159
### Command-Line Interface
160

161
Complete command-line tools for freezing scripts and generating setup configurations without requiring Python programming.
162

163
```python { .api }
164
def main() -> None  # cxfreeze command
165
def main() -> None  # cxfreeze-quickstart command
166
```
167

168
[Command-Line Tools](./cli-tools.md)
169

170
### Advanced Freezing Control
171

172
Direct access to the freezing engine for programmatic control over module discovery, dependency analysis, and executable creation.
173

174
```python { .api }
175
class Freezer:
176
    def __init__(
177
        self,
178
        executables: Sequence[Executable, Mapping[str, str], str],
179
        constants_module: ConstantsModule | None = None,
180
        includes: list[str] | None = None,
181
        excludes: list[str] | None = None,
182
        packages: list[str] | None = None,
183
        # ... additional configuration
184
    )
185

186
class ModuleFinder:
187
    # Module discovery and analysis methods
188

189
class Module:
190
    # Module representation and manipulation
191
```
192

193
[Advanced Freezing](./advanced-freezing.md)
194

195
## Types
196

197
```python { .api }
198
# Core exception types
199
class OptionError(Exception):
200
    """Raised when an error is detected in configuration."""
201

202
class SetupError(Exception):
203
    """Raised for setup script errors."""
204

205
class ModuleError(Exception):
206
    """Raised when there are problems loading modules."""
207

208
class FileError(Exception):
209
    """Raised for file/resource not found errors."""
210

211
class BindError(Exception):
212
    """Raised for Windows resource binding errors (Windows only)."""
213

214
# Platform-specific types (Windows only)
215
HANDLE = int | None  # Windows resource handle type
216
```