Format:BEAM (Erlang and Elixir compiled module)
| Magic | 46 4F 52 31 (FOR1), size u32 BE, 42 45 41 4D (BEAM) |
|---|---|
| Extensions | .beam |
| Endianness | big |
| License | Apache-2.0 (erlang/otp) |
| On this wiki | Facts · Code · Notes · Topics |
Compiled module of the Erlang VM (.beam, also produced by Elixir and Gleam): an IFF-style container with form id FOR1 and form type BEAM, holding 4-character chunks (AtU8, Code, StrT, ImpT, ExpT, LitT, Attr, CInf, Line, ...) padded to 4 bytes.
Overview
A .beam file is an IFF-style form: the bytes FOR1, a big-endian 32-bit size, the form type BEAM, then a sequence of chunks. Each chunk is a 4-character id, a big-endian 32-bit size, the data, and zero padding up to the next 4-byte boundary (the size field does not include the padding). All of this is read from erts/emulator/beam/beam_file.c (iff_init, read_beam_chunks) and written by lib/compiler/src/beam_asm.erl (build_form, chunk) at erlang/otp commit d7e0d97ce13a (see Fact:BEAM (Erlang and Elixir compiled module)/magic/FOR1 container).
The loader rejects a file whose IFF form type is not BEAM with the message "not a BEAM file: IFF form type is not 'BEAM'".
Chunks
The chunk ids the emulator itself looks for are AtU8 (UTF-8 atom table), Code, StrT (string table), ImpT (imports), ExpT (exports), FunT (lambdas), LitT (literals), Attr (attributes), CInf (compile info), Line, LocT (local functions, only used by the JIT build), Atom (obsolete Latin-1 atom table, reported as an obsolete table), Type, Meta, DbgB and Recs. Chunks that tools add without the emulator reading them include Dbgi (debug info) and Docs (the documentation chunk); both ids appear in lib/compiler/src/compile.erl. Unverified: Elixir and Gleam modules use the same container and chunk set (Elixir normally stores its debug info in Dbgi); check with any compiled Elixir .beam.
The assembler writes the chunks in this order: AtU8, Code, StrT, ImpT, ExpT, FunT, LitT, Meta, Recs, DbgB (the essential chunks, whose MD5 becomes the module's vsn), then LocT, Attr, CInf, any extra chunks such as Dbgi, Line, Type. With the slim option only the essentials, Attr and Type are written. The Attr and CInf chunks hold Erlang external term format (term_to_binary) data.
Code chunk header
The Code chunk starts with a 16-byte sub-header: the header length (16), the instruction set version (BEAM_FORMAT_NUMBER, 0 in genop.tab), the highest opcode used by the module, the number of labels and the number of functions; all u32 big-endian. The loader requires the version to be exactly BEAM_FORMAT_NUMBER and skips the header length given in the first word. Opcode numbers come from lib/compiler/src/genop.tab (it contains numbered entries such as 1: label/1 and 2: func_info/3; the last numbered entry at the commit is 193, update_record_id/7). See Fact:BEAM (Erlang and Elixir compiled module)/struct/Code chunk header.
LitT compression changed in OTP 28
LitT starts with a u32. Up to Erlang/OTP 27 it is the uncompressed size and the rest is a zlib stream; from OTP 28 a zero word means the literal table follows uncompressed (zero cannot be a valid size because the chunk is only written when there is at least one literal). A parser must handle both. See Fact:BEAM (Erlang and Elixir compiled module)/behavior/LitT compression.
The AtU8 chunk changed in the same release: the assembler writes a negative atom count and encodes each atom length with the compact tagged integer encoding when no_long_atoms is not set; with that option it writes the older format with a positive count (beam_asm.erl build_atom_table). Unverified: the older layout is a count followed by a one-byte length and the UTF-8 text per atom.
Identification
A file starting FOR1 with BEAM at offset 8 is a BEAM module. The same FOR1 container with other form types is not covered here.
Code & repositories
- https://github.com/erlang/otp @
d7e0d97ce13ac4a16af25a072c86a7927dbf0d55· license: Apache-2.0
Erlang/OTP: beam_file.c (loader), beam_asm.erl (writer), genop.tab (opcodes).
Tested on: source read, not run: read source only · checked 2026-10-19; last activity 2026-10-19; Note: the latest release ships binaries; the wiki links only the source, never the binaries
Evidence & references
- erlang/otp, erts/emulator/beam/beam_file.c, lib/compiler/src/beam_asm.erl, lib/compiler/src/genop.tab, lib/compiler/src/compile.erl at d7e0d97ce13a (Apache-2.0).