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

🤝 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!
• ☕ 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.

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 │
    └─────────┬─────────┘ └─────────┬─────────┘ └─────────┬─────────┘
              │                   │                   │
              └───────────────────┼───────────────────┘
                                  ▼ (Bundled FASM Assembler)
              ┌───────────────────┼───────────────────┐
              ▼                   ▼                   ▼
    [ Windows PE64 .exe ]  [ Linux ELF64 .elf ] [ Apple Mach-O .macho ]
         (~2.5 KB)               (~1.8 KB)           (~2.4 KB)

Platform Architecture Comparison

Deep Dive: Supported OS Architectures

1. Windows x86-64 Architecture (--target win64, --target dll)

• PE64 Header Structure: PyFASM64 emits valid Portable Executable (PE32+) headers matching the Windows loader specification. The file contains .text (executable code), .data (writable static variables and strings), and .idata (Import Directory Table for kernel32.dll).
• Calling Convention: Strictly adheres to the Microsoft x64 Calling Convention. The compiler automatically provisions the required 32-byte shadow space (home space) before every API call and ensures the stack pointer (RSP) is aligned to a 16-byte boundary prior to call instructions.
• Shared Libraries (--target dll): Emits proper Export Directory Tables with IMAGE_FILE_DLL characteristics, allowing Python modules compiled by PyFASM64 to be loaded instantly via Python's standard ctypes.CDLL or linked by C/C++ applications.

2. Linux x86-64 Architecture (--target linux)

• ELF64 Executable Header: Uses FASM's native format ELF64 executable 3 targeting System V ABI without requiring external linkers (ld) or GCC.
• Pure Direct Syscalls: Implements all system services through direct x86_64 syscall instructions:
  • sys_write (rax = 1): Outputs text directly to stdout file descriptor (rdi = 1).
  • sys_exit (rax = 60): Terminates the process cleanly with the return code in rdi.
  • sys_mmap (rax = 9): Dynamically allocates memory pages with PROT_READ | PROT_WRITE and MAP_PRIVATE | MAP_ANONYMOUS.
  • sys_munmap (rax = 11): Unmaps allocated pages back to the kernel.
  • sys_nanosleep (rax = 35): High-precision thread sleep without external libraries.
• Universal Portability: Because PyFASM64 does not link against libc.so.6, the generated binaries run unchanged on any Linux distribution, including Alpine Linux (musl), Ubuntu, Debian, Red Hat, Arch Linux, and container base images (scratch, busybox).

3. Apple macOS x86-64 Architecture (--target macos / --target apple)

• Mach-O 64-bit Header: Emits a compliant 64-bit Mach-O binary (MH_MAGIC_64 = 0xFEEDFACF) with CPU_TYPE_X86_64 and CPU_SUBTYPE_LIB64.
• Direct Kernel Load Commands: Employs LC_SEGMENT_64 (defining the __TEXT segment and __text section) combined with LC_UNIXTHREAD to initialize the CPU state and register pointer (RIP) directly to the PyFASM64 entry point.
• Darwin BSD Syscall Class: Darwin 64-bit syscalls utilize the BSD system call class mask 0x2000000:
  • sys_write: rax = 0x2000004 (rdi = 1, rsi = buffer, rdx = length).
  • sys_exit: rax = 0x2000001 (rdi = exit code).
  • sys_mmap: rax = 0x20000C5 (anonymous private memory pages).
  • sys_nanosleep: rax = 0x20000EB (thread sleep).
• Zero dyld Overhead: Bypasses Apple's dynamic linker dyld and libSystem.B.dylib entirely, resulting in standalone executables that start instantaneously without security dyld-cache overhead.

Cross-Platform Project Bundler (pyfasm64 bundle)

The PyFASM64 bundler creates native standalone launcher executables that package complex Python applications for Windows, Linux, and Apple macOS:

# Bundle for Windows (generates native PE64 app.exe):
uv run pyfasm64 bundle ./my_app -o ./my_app/app.exe --target win64

# Bundle for Linux (generates native ELF64 app.elf using direct sys_execve):
uv run pyfasm64 bundle ./my_app -o ./my_app/app.elf --target linux

# Bundle for Apple macOS (generates native Mach-O app.macho using Darwin syscalls):
uv run pyfasm64 bundle ./my_app -o ./my_app/app.macho --target macos

(Note: pyfasm bundle ... can be used interchangeably)

How It Works:

1. Virtual Environment Auto-Detection: Inspects the project directory for .venv, locating local project virtual environments.
2. No-GIL / Free-Threaded Detection: Checks .python-version and system configuration; if a free-threaded Python build (3.13t-3.16t) is detected, it automatically executes with -X gil=0 to unlock true multicore parallelism.
3. Pure Native Launcher: The launcher itself is an ultra-fast compiled binary (~350 bytes to 2.5 KB) that sets PYTHONUNBUFFERED=1 and spawns the application process with zero startup latency.

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_0.1.1-1_all.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. 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

2. 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

3. 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

4. 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

5. Inspect Generated FASM Assembly

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

6. Compile to High-Performance Windows DLL

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

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

tests/test_bundler.py ......                                             [ 22%]
tests/test_codegen.py ...                                                [ 33%]
tests/test_execution.py .............                                    [ 81%]
tests/test_fasm_exporter.py ..                                           [ 88%]
tests/test_multithreading.py .                                           [ 92%]
tests/test_parser.py .                                                   [ 96%]
tests/test_types.py .                                                    [100%]
============================== 27 passed in 1.69s ==============================

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.