PyFASM64: Universal Python-to-Pure FASM x86_64 Native Compiler

🌐 Language / Язык: English | 🇷🇺 Русский (Russian Documentation)

🤝 Community, Issues & Support

• 🐛 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) or pyfasm 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 pyfasm64 and pyfasm commands are installed and supported out of the box.
• Dual Python Imports: Both import pyfasm64 and import pyfasm work 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.

What's New in v0.1.14: FASM Modern SDK Integration

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):

1. 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 INCLUDE environment variable setup required.
2. 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.
3. 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.
4. Built-in Interactive Documentation:
   • View English documentation: pyfasm docs
   • View Russian documentation: pyfasm docs --ru
   • Open documentation in markdown viewer/browser: pyfasm docs --open

Key Features

• True Zero-GIL Multithreading:
  • Compiled executables run directly on bare metal without any Python VM or interpreter lock.
  • Native OS kernel threads (CreateThread on Windows, sys_clone on 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 via ctypes or 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 import and from ... import ... statements, registers aliases, and prevents circular dependencies while strictly skipping external/virtualenv directories.
• 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.

Compiler Architecture

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)

Platform Architecture Comparison

Installation

Via PyPI (Official Python Package Index)

# Using uv (recommended)
uv add pyfasm64

# Using standard pip
pip install pyfasm64

Via Conda (conda-forge organization channel)

# Using standard conda
conda install -c conda-forge pyfasm64

# Or using mamba
mamba install -c conda-forge pyfasm64

# Or using pixi
pixi add pyfasm64

Via Debian / Ubuntu PPA (eminsk/ppa)

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_*.deb

From Source

git clone https://github.com/eminsk/pyfasm.git
cd pyfasm
uv sync

CLI Usage

Both pyfasm64 and pyfasm CLI commands are available and identical in syntax and options:

1. View Built-in Documentation

# 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

2. Compile and Run on Windows (PE64)

# 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

3. Compile for Linux (ELF64)

# 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

4. Compile for Apple macOS (Mach-O 64)

# 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

5. Compile Multi-Module Project into 1 Single Standalone Binary

# 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.exe

6. Inspect Generated FASM Assembly

uv run pyfasm64 emit-asm examples/02_fibonacci.py

7. Compile to High-Performance Windows DLL

uv run pyfasm64 compile my_math.py -o my_math.dll --target dll

8. Export Full FASM Project Folder

# Exports assembly, headers, compiler, and 1-click build scripts into FASM/ directory:
uv run pyfasm compile my_app.py --export-fasm

9. Application Icon & Windows PE Resources

# 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

10. Clean Compiler & Build Caches

# 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

Supported Python Language Subset

Benchmark Comparison

Tested on AMD / Intel x86_64 (Windows 11 & Linux 6.x):

Testing & Verification

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.

License

This project is licensed under the MIT License.