Molt

Molt is an optimizing Python-to-native and WebAssembly compiler with a Rust-owned runtime and explicit compatibility boundaries.

Molt is under active development, not a drop-in replacement for CPython. Its Python contract limits excessive dynamism to preserve efficient compilation and standalone execution. Verification records which configurations have passed conformance; incomplete implementation does not narrow that contract. Language, stdlib, third-party package support, and native/WASM parity remain incomplete; see current status before choosing a workload.

The first public release is numbered v0.0.1 and must meet the full v1.0 quality standard; the version number does not lower the bar. It does not imply Python or ecosystem compatibility beyond its verified subset. See the release milestone. Release readiness also requires the declared workload and resource budgets in the performance authority. Every release, including v0.0.1, requires the complete same-source E1-E4 exit bundle: the native/WASM NumPy/SciPy witness, native/LLVM performance, verified-subset compatibility and structural gates, with no open finding and an authenticated H0 phase exit. See the release contract. These gates do not imply that the remaining release matrix has passed. The Pact acceptance lanes bind native/WASM execution and oracle parity to portable, source-pinned receipts; package seals or successful builds alone do not establish acceptance. The verified-subset contract defines test selection, source-change checks, and the exact cross-target pass law.

Why Molt

• Standalone output: compiled binaries do not rely on a host Python installation.
• Rust-first runtime: hot semantics and stdlib behavior are pushed down into runtime primitives and intrinsics; the rest of the stdlib compiles from its Python source like your code, never through a host interpreter.
• Evidence-backed compatibility: differential tests compare supported behavior with CPython; support is scoped to the tested configuration.
• Co-equal targets: native and WASM correctness, determinism, performance, and binary size are engineering goals, not a claim of completed parity.

Project Contract

• CPython >=3.12 parity target within the declared Python contract, governed by version-pinned CPython source and applicable official PEPs. Current target-version policies are 3.12, 3.13, and 3.14; accepting a version policy does not certify every feature on that version. The Python running the CLI must be at least the selected target minor; see frontend selection. Python 3.15 support across the release matrix is a required v1.0 exit obligation; its implementation and qualification remain open in the release ledger.
• Compiled artifacts must work without a host Python installation.
• CPython module names retain their standard-library role. Molt-specific helpers live under moltlib, including moltlib.io.stream for bounded file iteration; they are not extensions to CPython's io namespace.
• Support is specific to Python version, OS, architecture, backend, runtime profile, and capabilities. Windows, macOS, Linux, and WASM are in scope; unverified cells are not implied by a pass on another configuration.
• Dynamic execution and reflection follow the dynamic-semantics policy. Scoped mutation and introspection are not a promise of arbitrary runtime monkeypatching or unrestricted dynamism.

What Molt Supports Today

• Native AOT compilation through Cranelift by default, with opt-in LLVM code generation. The production compiler build includes the pinned static LLVM feature; installed use requires an admitted compiler and runtime cell. Host/backend release qualification remains subject to the verified support matrix. The experimental Rust source emitter is a separate backend.
• Standalone binary workflows with no runtime dependency on local CPython.
• A growing Rust-first stdlib lowering program with generated audit surfaces.
• Differential testing against CPython as a core validation path.
• WASM build workflows, with cross-target parity still incomplete and actively tracked. The Node runner uses WASI plus Molt's host imports and deployment manifest. Current deployments require manifest version 4; rebuild older deployments with the current compiler and matching runner assets. Deployments need the matching runner assets or an admitted host adapter; a linked module alone does not certify an arbitrary WASI host.
• Third-party integration through shared import/runtime primitives and source-recompiled extensions. C-API symbol coverage alone does not establish package compatibility. See the extension ABI contract for header and runtime-linkage requirements, and the ecosystem matrix for package support. Final links with checksummed native dependencies publish a member-selection sidecar alongside their outputs; missing or changed evidence invalidates cache reuse. Unbound library providers must be resolved to checksummed static inputs. See the source-build contract for linker capability gates and the remaining lazy-source admission boundary.

Install

Use a prebuilt distribution for your platform when its release is available: a downloaded platform wheel installed with pip install <wheel-path>, a published package-manager distribution, or a GitHub release bundle. The current release workflow produces wheel assets but has no PyPI upload step; the pip install molt registry route still requires publication. The compiler and runtime ship prebuilt; compiling your program does not require building Molt or installing Rust. See binary installation for requirements, available installation routes, and standalone execution limits.

Binary bundles require explicit dependency setup with molt setup --install-cli-dependencies; normal launches do not install or repair dependencies. Platform wheels use their pip environment. molt doctor identifies the active installation, runtime availability, and competing PATH entries. Source contributors use the checkout instructions below. The compiler host must use CPython 3.12+; Python 3.14 hosts require 3.14.1 or newer. See the host and target requirements.

• Package and installer paths: see docs/getting-started.md
• Packaging details: packaging/README.md
• Installation diagnostics: molt doctor --json (not a compatibility or release certification).

Source Checkout Quickstart

For the full setup and troubleshooting path, use docs/getting-started.md.

uv sync --group dev --python 3.12.15
uv run --python 3.12 molt doctor --json
uv run --python 3.12 molt run examples/hello.py

Run these commands from the repository root after installing the prerequisites. uv sync creates the project environment but does not activate it; uv run selects it without shell-specific activation. The first build may compile the backend and runtime. These commands maintain a source bootstrap environment. Managed development and proof commands use the separate immutable image contract described in checkout provisioning; do not point uv sync at a published image. For the supported change-to-CI path, failure triage and source-bound proof coverage verification, see the developer workflow. For another supported Python target, select its frontend through uv and its language policy through --python-version; see version selection.

uv run --python 3.12 molt run examples/hello.py --release
uv run --python 3.12 molt compare examples/hello.py

molt run defaults to dev; molt build defaults to release. Both accept --profile dev|release and --release. Dev builds optimize the established hot runtime family while retaining runtime checks; see the profile policy. Source-checkout WASM runtime builds keep their nonincremental default for both profiles; explicit iteration and Cargo controls are described in build-time controls. For explicit output paths and Windows, macOS, and Linux invocation, see build and run. On macOS arm64, molt run --tier jit runs the program from memory with no object file, link or native executable. It compiles the whole program on every start, so it is slower than the default AOT tier for any program that imports os; see the JIT tier.

Final-link reuse checks the complete output family against its receipt. Linked WASM deployment files are published together; failed builds preserve the previous generation. Keep the hidden .molt-artifact-* custody files beside local outputs, but exclude them from deployment packages. See the publication contract. WASM package bundles normalize host metadata and use portable paths; unsupported or colliding archive names fail with a diagnostic before replacing prior output.

These profiles select optimization of your program, not the compiler itself. Release bundles, package-manager installs and platform wheels ship a production-optimized compiler, WASM inspection tool and prebuilt runtimes for the required release lanes. Native and LLVM share physical runtime cells while retaining distinct compiled products. Installed compilation never builds Rust or provisions an LLVM SDK. Compiler developers can opt into a development host build with MOLT_BACKEND_PROFILE=dev in a source checkout. --diagnostics reports the compiler identity/profile separately from the program and runtime profiles, together with build-phase and cache information.

Build/run progress adapts to stderr: an interactive indicator on terminals, bounded phase lines in logs. Use --headless or --progress plain for plain status, --progress off to disable status, or --quiet to suppress successful compiler notices too. Errors and guest output remain visible; JSON mode emits no progress chatter.

Status

Current detailed state lives in docs/spec/STATUS.md. Forward direction lives in ROADMAP.md; open findings and the burn-down order live in the findings ledger. Correctness, installed compile latency, generated-program performance, memory, startup, and delivered size remain release priorities; a passing demonstration does not qualify v1.0.

For compatibility and proof detail:

• Docs index: docs/INDEX.md
• Spec index: docs/spec/README.md
• Compatibility architecture: docs/spec/areas/compat/README.md
• Dated benchmark report: docs/benchmarks/bench_summary.md (read its source revision, timing mode, and comparator coverage; it does not establish current performance or superiority to unmeasured compilers).
• Application benchmark inputs and qualification limits: bench/corpus/README.md.
• Standalone proof workflow: docs/proofs/STANDALONE_BINARY_PROOF_WORKFLOW.md

Development

Use molt dx run -- <command> for bounded local iteration. Its persistent Cargo intermediates belong to one checkout; sibling worktrees share compiler/download caches, not mutable Cargo targets. See the developer build guidance for explicit target overrides and separate queued release qualification.

To place transient scratch on a chosen local disk, set MOLT_SCRATCH_STORAGE=disk:/absolute/existing/directory. This changes data scratch placement while control state, build products and caches stay in their configured locations. Default disk scratch belongs to one lane under <artifact root>/tmp/scratch-<checkout path digest> and retires after three idle days into a recoverable seven-day holding area. See scratch storage and budget for defaults, memory-backed storage and free-space admission.

Managed compiler/runtime source builds keep Cargo intermediates with the captured external toolchain inputs; ordinary source edits retain incremental state. Python table generators have a separate interpreter signature. These development checks add no work or Python dependency to emitted programs. See build input freshness.

• Contributor map: docs/DEVELOPER_GUIDE.md
• Operations and multi-agent workflow: docs/OPERATIONS.md
• Build storage, output lifetimes, and proof custody: docs/agent/PROOF_QUEUE.md
• Proof run evidence retention (molt queue retention): docs/agent/PROOF_QUEUE.md
• Shared frontend analysis, streaming AST/tooling identities, and live import resolution: source scan authority
• Benchmark workflows: docs/BENCHMARKING.md