PyFASM: 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 PyFASM useful? Give it a star on GitHub — it helps more developers discover the compiler!
• ☕ Support development (USDT TRC-20): TDVbEdnpgNgoAhNcn1EwXxWHiR3RKLit5P (Verify on TronScan)

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). PyFASM produces native binaries without external dependencies across native target formats: Windows (.exe, .dll), Linux (ELF64), and Apple macOS (Mach-O 64).

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 (pyfasm 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

PyFASM 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: PyFASM 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 PyFASM 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 PyFASM 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 PyFASM 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 (pyfasm bundle)

The PyFASM 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 pyfasm bundle ./my_app -o ./my_app/app.exe --target win64

# Bundle for Linux (generates native ELF64 app.elf using direct sys_execve):
uv run pyfasm 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 pyfasm bundle ./my_app -o ./my_app/app.macho --target macos

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 Conda (conda-forge organization channel)

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

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

# Or using pixi
pixi add pyfasm

Via Debian / Ubuntu PPA (eminsk/ppa)

sudo add-apt-repository ppa:eminsk/ppa
sudo apt update
sudo apt install python3-pyfasm

Alternatively, download the latest python3-pyfasm_*.deb from the GitHub Releases page:

sudo dpkg -i python3-pyfasm_0.1.0-1_all.deb

Via uv / pip

# Using uv (recommended)
uv add pyfasm

# Using standard pip
pip install pyfasm

From Source

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

CLI Usage

1. Compile and Run on Windows (PE64)

# Compile to native Windows x64 .exe and execute immediately:
uv run pyfasm compile examples/01_hello.py --run

# Compile parallel multithreading benchmark:
uv run pyfasm 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 pyfasm 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 pyfasm 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 pyfasm compile ./my_project -o my_app.exe

# Or compile from entry script (auto-resolves all imported helper modules):
uv run pyfasm compile my_project/main.py -o my_app.exe

5. Inspect Generated FASM Assembly

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

6. Compile to High-Performance Windows DLL

uv run pyfasm 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, and type checking across all supported Python versions:

uv run pytest

tests/test_codegen.py ...                                                [ 17%]
tests/test_execution.py ...........                                      [ 82%]
tests/test_multithreading.py .                                           [ 88%]
tests/test_parser.py .                                                   [ 94%]
tests/test_types.py .                                                    [100%]
============================== 17 passed in 0.56s ==============================

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.