Cosmopolitan Libc — Build Once, Run Anywhere C/C++ Executables

Introduction

Cosmopolitan Libc is a C library that lets you compile C and C++ programs into Actually Portable Executables (APE). A single binary produced with Cosmopolitan runs on six operating systems and multiple architectures without any recompilation, emulation, or container layer. It was created by Justine Tunney to make cross-platform native code distribution trivially simple.

What Cosmopolitan Does

• Produces single-file executables that run natively on Linux, macOS, Windows, FreeBSD, OpenBSD, and NetBSD
• Provides a POSIX-compatible C library with extensions for modern systems programming
• Bundles a toolchain (cosmocc) based on GCC that cross-compiles for all supported targets at once
• Supports both x86-64 and ARM64 architectures in the same binary via fat APE format
• Includes optimized implementations of libc functions tuned for each target OS at runtime

Architecture Overview

Cosmopolitan works by embedding a polyglot binary header that is valid as a Unix shell script, a Windows PE executable, and a macOS Mach-O binary simultaneously. At load time, a tiny boot stub detects the host operating system and architecture, then jumps to the appropriate code path. The C library translates POSIX system calls to native OS calls on each platform, so application code uses a single standard API. The cosmocc toolchain wraps GCC to produce these APE binaries by linking against Cosmopolitan instead of the system libc.

Self-Hosting & Configuration

• Download the cosmocc toolchain from cosmo.zip and extract it
• Use cosmocc as a drop-in replacement for gcc or cc in build scripts
• Set CC=cosmocc and CXX=cosmoc++ to integrate with Makefiles and CMake projects
• Link with -static by default since Cosmopolitan produces fully static binaries
• Deploy the output binary directly to any supported OS with no runtime dependencies

Key Features

• True write-once, run-anywhere native executables without a VM or interpreter
• Full POSIX threads, sockets, and file I/O support across all six operating systems
• Fat binary format supporting both x86-64 and ARM64 in a single file
• Small binary overhead — the runtime stub adds minimal size compared to the application code
• Powers the llamafile project, which distributes LLMs as single portable executables

Comparison with Similar Tools

• Go cross-compilation — Go can target multiple OS/arch pairs but produces separate binaries per target; Cosmopolitan ships one binary for all platforms
• Docker / containers — containers isolate at the OS level and require a runtime; Cosmopolitan runs natively with zero dependencies
• musl-libc static builds — musl produces static Linux binaries; Cosmopolitan extends this to macOS, Windows, and BSDs in one file
• GraalVM native-image — compiles JVM apps to native binaries per platform; Cosmopolitan targets C/C++ and covers more OSes per binary
• Zig cross-compilation — Zig's toolchain cross-compiles C/C++ for many targets; Cosmopolitan uniquely bundles all targets into a single polyglot executable

FAQ

Q: Does the binary need to be renamed or given an extension on Windows? A: APE binaries can be run directly on modern Windows versions. Older systems may need the file renamed with a .exe extension or the APE loader installed.

Q: Can I use third-party C libraries with Cosmopolitan? A: Yes, as long as they compile with standard C and link statically. Many popular libraries have been ported and tested.

Q: How large is a typical Cosmopolitan binary? A: A minimal hello-world binary is around 100 KB. Real applications vary based on which libc features they pull in.

Q: Is it production-ready? A: Yes. Cosmopolitan powers production tools like llamafile and has been tested across major operating systems and cloud providers.

Sources

• https://github.com/jart/cosmopolitan
• https://cosmo.zip