🌐 Language / Язык: English | 🇷🇺 Русский (Russian Documentation)
-26A17B?style=flat&logo=tether&logoColor=white){kind=icon}
- 🐛 Found a bug, compiler issue, or edge case? Please Open an Issue — bug reports and platform patches are tracked and resolved quickly!
- 💬 Questions, cross-compilation ideas, or new architectures? Join our GitHub Discussions.
- ⭐ Find PyFASM64 useful? Give it a star on GitHub — it helps more developers discover the compiler!
- 📖 Documentation: Read online on GitHub, or use the CLI:
pyfasm docs(English) orpyfasm docs --ru(Russian).- ☕ Support development (USDT TRC-20):
TDVbEdnpgNgoAhNcn1EwXxWHiR3RKLit5P(Verify on TronScan)
PyFASM64 (package: pyfasm64, legacy alias: pyfasm) is a high-performance cross-platform native compiler that translates Python code directly into pure x86_64 Flat Assembler (FASM) machine code. It generates tiny, self-contained standalone binaries with zero runtime overhead, no virtual machine, and complete elimination of the Global Interpreter Lock (Zero-GIL).
It supports hosting on CPython 3.8–3.16, Free-Threaded / No-GIL Python (3.13t–3.16t), and PyPy (3.8–3.12). PyFASM64 produces native binaries without external dependencies across native target formats: Windows (.exe, .dll), Linux (ELF64), and Apple macOS (Mach-O 64).
💡 100% Backward Compatibility: PyFASM64 preserves every existing capability and workflow of classic PyFASM:
- Dual CLI Commands: Both
pyfasm64andpyfasmcommands are installed and supported out of the box.- Dual Python Imports: Both
import pyfasm64andimport pyfasmwork seamlessly.- Zero Breaking Changes: All compiler options, multi-module imports, targets (
win64,linux,macos,dll), benchmarks, and the native bundler operate with complete backward compatibility.
Starting with v0.1.14, PyFASM64 bundles and deeply integrates the FASM Modern SDK (fasm-modern-sdk v1.73.36 and fasmg v0.0.26):
- Self-Contained Compiler & Headers:
- The official wheel packages contain all required FASM compiler binaries (
FASM.EXE,fasmg.exe,fasm.x64,fasm.darwin,fasm) and standard Win64/Win32 includes (win64a.inc,win32a.inc, equates, macros). - Zero configuration needed: no
INCLUDEenvironment variable setup required.
- The official wheel packages contain all required FASM compiler binaries (
- Modern SDK Include Modules:
ui_fluent.inc: High-performance Modern Fluent Dark UI styling, owner-drawn controls, and smooth rounded cards.json_fast.inc: Zero-allocation SIMD-accelerated JSON parser.net_https.inc: Zero-dependency native WinINet/POSIX sockets HTTPS/TLS network client.data_structures.inc: Dynamic array vectors, string buffers, and hash tables.syntax_color.inc: Lexical tokenization and realtime syntax highlighting engine.
- Unicode & UTF-8 / UTF-16LE Engine:
- Integrated native runtime conversion (
_pyfasm_utf8_to_wide), eliminating Windows Mojibake (corrupted Chinese characters in GUI labels, textboxes, and buttons). - GUI control collision prevention: automatically reuses existing window handles to avoid duplicate listboxes or overlapping frames.
- Integrated native runtime conversion (
- Built-in Interactive Documentation:
- View English documentation:
pyfasm docs - View Russian documentation:
pyfasm docs --ru - Open documentation in markdown viewer/browser:
pyfasm docs --open
- View English documentation:
-
True Zero-GIL Multithreading:
- Compiled executables run directly on bare metal without any Python VM or interpreter lock.
- Native OS kernel threads (
CreateThreadon Windows,sys_cloneon Linux) run concurrently across all physical CPU cores at 100% capacity. - Hardware atomic memory operations via x86_64 CPU instructions (
lock add,lock sub).
-
Ultra-Compact Binary Footprint:
- Standalone executables range from 512 bytes (flat bare-metal binary) to 2.5 KB (PE64 / ELF64 / Mach-O 64).
- Absolutely zero external dependencies: no
python.exe, no MSVCRT, no libc/glibc, and no external dynamic linkers required.
-
Bare-Metal Execution Speed:
- Pure x86_64 assembly performance on par with hand-tuned C and assembly.
- Fibonacci calculation (
$N=40$ ): 0 ms. - Sieve of Eratosthenes (100,000 prime numbers): 0 ms.
- 8 parallel threads executing 2,000,000 atomic operations: 47 ms.
-
Comprehensive Cross-Platform Targets:
-
--target win64: Standalone Windows 64-bit PE64 Console executables (.exe). -
--target dll: Windows 64-bit Dynamic Link Libraries (.dll) callable instantly from Python viactypesor from C/C++. -
--target linux: Native Linux x86-64 ELF64 executables (.elf) using pure kernel syscalls (sys_write,sys_exit,sys_mmap,sys_nanosleep) with zero libc dependency. -
--target macos/--target apple: Apple macOS x86-64 Mach-O 64-bit executables (.macho) using direct Darwin BSD kernel syscalls.
-
-
Multi-Module Single-File Compilation:
- Automatically discovers and compiles all internal modules, subpackages, and libraries in a project into a single standalone machine code binary (
.exe,.elf,.macho). - Recursively traverses local
importandfrom ... import ...statements, registers aliases, and prevents circular dependencies while strictly skipping external/virtualenv directories.
- Automatically discovers and compiles all internal modules, subpackages, and libraries in a project into a single standalone machine code binary (
-
Cross-Platform Project Bundler (
pyfasm64 bundle):- Bundles complex Python applications into native standalone launcher executables for Windows (
.exe), Linux (.elf), and Apple macOS (.macho) that automatically discover virtual environments and launch in Free-Threaded (No-GIL) mode when available.
- Bundles complex Python applications into native standalone launcher executables for Windows (
PyFASM64 is architected from the ground up as a retargetable, zero-runtime compiler with distinct frontend, semantic, and platform code-generation layers:
┌────────────────────────────┐
│ Python Source Code │
│ (Python 3.8 - 3.16t) │
└─────────────┬──────────────┘
│
▼ (Python ast parser)
┌────────────────────────────┐
│ Abstract Syntax Tree │
└─────────────┬──────────────┘
│
▼ (AstAnalyzer)
┌────────────────────────────┐
│ Semantic & Type Analysis │
│ (int, ptr, str, stack) │
└─────────────┬──────────────┘
│
▼ (Target ABI & Syscall Selector)
┌───────────────────┼───────────────────┐
▼ ▼ ▼
┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐
│ Windows PE64 │ │ Linux ELF64 │ │ Apple macOS Mach-O│
│ - Microsoft x64 │ │ - System V ABI │ │ - Darwin BSD │
│ - Shadow Space │ │ - Pure Syscalls │ │ - 0x2000000 Sys │
└─────────┬─────────┘ └─────────┬─────────┘ └─────────┬─────────┘
│ │ │
└───────────────────┼───────────────────┘
▼ (FASM Modern SDK Assembler v1.73.36)
┌───────────────────┼───────────────────┐
▼ ▼ ▼
[ Windows PE64 .exe ] [ Linux ELF64 .elf ] [ Apple Mach-O .macho ]
(~2.5 KB) (~1.8 KB) (~2.4 KB)
| Architectural Aspect | Windows x86-64 | Linux x86-64 | Apple macOS x86-64 |
|---|---|---|---|
| Binary Format | PE32+ (PE64) Console / DLL | ELF64 Executable (Type 3) | Mach-O 64 (MH_MAGIC_64) |
| Magic Header | MZ (0x5A4D) / PE\0\0 |
\x7fELF (0x464C457F) |
0xFEEDFACF (Little-Endian) |
| ABI Calling Convention | Microsoft x64 ABI | System V AMD64 ABI | System V AMD64 ABI |
| Register Parameters | RCX, RDX, R8, R9 |
RDI, RSI, RDX, RCX, R8, R9 |
RDI, RSI, RDX, RCX, R8, R9 |
| Stack Shadow Space | 32 bytes reserved by caller | None (128-byte Red Zone) | None (128-byte Red Zone) |
| Kernel Interface | Win32 API (kernel32.dll) |
Direct Linux Kernel Syscalls | Direct Darwin BSD Syscalls |
| Standard Output | GetStdHandle + WriteFile |
syscall (rax = 1 sys_write) |
syscall (rax = 0x2000004) |
| Process Termination | ExitProcess (code in RCX) |
syscall (rax = 60 sys_exit) |
syscall (rax = 0x2000001) |
| Memory Allocation | VirtualAlloc (MEM_COMMIT) |
syscall (rax = 9 sys_mmap) |
syscall (rax = 0x20000C5) |
| High-Precision Time | GetTickCount / RDTSC |
sys_nanosleep (35) / RDTSC |
sys_nanosleep (0x20000EB) / RDTSC |
| Runtime Dependencies | None (kernel32 only) | Zero libc / Zero glibc | Zero libSystem / Zero dyld |
# Using uv (recommended)
uv add pyfasm64
# Using standard pip
pip install pyfasm64
# Using standard conda
conda install -c conda-forge pyfasm64
# Or using mamba
mamba install -c conda-forge pyfasm64
# Or using pixi
pixi add pyfasm64
sudo add-apt-repository ppa:eminsk/ppa
sudo apt update
sudo apt install python3-pyfasm64(Also satisfies dependencies requiring python3-pyfasm)
Alternatively, download the latest python3-pyfasm64_*.deb from the GitHub Releases page:
sudo dpkg -i python3-pyfasm64_*.debgit clone https://github.com/eminsk/pyfasm.git
cd pyfasm
uv syncBoth pyfasm64 and pyfasm CLI commands are available and identical in syntax and options:
# View primary English documentation:
uv run pyfasm docs
# View Russian documentation:
uv run pyfasm docs --ru
# Open in default markdown viewer / editor:
uv run pyfasm docs --open# Compile to native Windows x64 .exe and execute immediately:
uv run pyfasm64 compile examples/01_hello.py --run
# Or using the classic pyfasm alias:
uv run pyfasm compile examples/01_hello.py --run
# Compile parallel multithreading benchmark:
uv run pyfasm64 compile examples/04_multithread_parallel.py --run# Generates native Linux x86-64 ELF executable using direct kernel syscalls:
uv run pyfasm64 compile examples/01_hello.py -o hello_linux.elf --target linux# Generates native Apple macOS x86-64 Mach-O binary using Darwin BSD syscalls:
uv run pyfasm64 compile examples/01_hello.py -o hello_mac.macho --target macos# Compiles an entire multi-file project into 1 standalone binary (auto-resolves all local imports):
uv run pyfasm64 compile ./my_project -o my_app.exe
# Or compile from entry script (auto-resolves all imported helper modules):
uv run pyfasm64 compile my_project/main.py -o my_app.exeuv run pyfasm64 emit-asm examples/02_fibonacci.pyuv run pyfasm64 compile my_math.py -o my_math.dll --target dll# Exports assembly, headers, compiler, and 1-click build scripts into FASM/ directory:
uv run pyfasm compile my_app.py --export-fasm# Compile with application icon embedded into PE resources (.rsrc), window, and taskbar:
uv run pyfasm compile main.py --icon icon.ico
# Auto-detects icon.ico if present in project directory:
uv run pyfasm bundle . -o MyApp.exe# Clean local project build artifacts (asm/, __pycache__, .stamp_*):
uv run pyfasm clean
# Dry-run to inspect items without deleting:
uv run pyfasm clean --dry-run
# Clean global unpacked application caches (%LOCALAPPDATA%/pyfasm):
uv run pyfasm clean --apps
# Clean all local and global caches:
uv run pyfasm clean --all| Feature | Syntax / API | Description |
|---|---|---|
| Functions | def name(a: int, b: int) -> int: |
Strongly-typed x86_64 functions with ABI calling conventions |
| Data Types | int, ptr, str, bool, void |
64-bit native integers, pointers, string constants, booleans |
| Arithmetic | +, -, *, //, %, &, |, ^, <<, >> |
Direct x86_64 ALU operations (add, sub, imul, idiv) |
| Control Flow | if, elif, else, while, for i in range() |
Conditional jumps, loops, break, continue, return |
| Dynamic Memory | alloc_memory(bytes), free_memory(ptr) |
OS virtual memory allocation (VirtualAlloc / sys_mmap) |
| Buffer Access | buf[i] = val and val = buf[i] |
Indexed memory read and write operations |
| Multithreading | spawn_thread(worker, param), wait_thread(h) |
Hardware OS threads running concurrently without GIL |
| Atomic Ops | atomic_add(ptr, val), atomic_sub(ptr, val) |
Thread-safe atomic operations via CPU lock prefix |
| Console I/O | print(), print_int(), print_str(), print_newline() |
Low-level buffered stdout streaming |
| Timers & Sleep | get_tick_count(), sleep_ms(ms) |
High-precision timing and thread sleep |
| Unicode Strings | str |
Transparent UTF-8 to UTF-16LE conversion for Win32 GUI APIs |
Tested on AMD / Intel x86_64 (Windows 11 & Linux 6.x):
| Benchmark | CPython 3.12 (Standard) | PyPy 3.10 (JIT) | PyFASM64 Native x64 | Speedup vs CPython |
|---|---|---|---|---|
| Fibonacci ( |
12,450 ms | 620 ms | < 1 ms | > 12,000x |
| Sieve of Eratosthenes (100k) | 185 ms | 18 ms | < 1 ms | > 180x |
| 8-Thread Parallel Counter | 4,210 ms (GIL contention) | 1,840 ms | 47 ms (Zero-GIL) | > 89x |
| Binary Size | ~35 MB (pyinstaller) | N/A | 2.5 KB | > 14,000x smaller |
The test suite covers codegen, execution, AST parsing, multithreading, multi-module bundler, and type checking across all supported Python versions:
uv run pytest============================= 48 passed in 6.37s ==============================
Verified compatibility matrix:
- CPython 3.8, 3.9, 3.10, 3.11, 3.12, 3.13, 3.14, 3.15, 3.16: 100% tests passing.
- Python Free-Threaded / No-GIL (3.13t, 3.14t, 3.15t, 3.16t): 100% tests passing.
- PyPy (3.8, 3.9, 3.10, 3.11, 3.12): 100% tests passing.
This project is licensed under the MIT License.