BeamSpy

objdump, strings, and readelf for the BEAM VM

BeamSpy is a BEAM file analysis tool that provides commands for inspecting compiled BEAM modules.

Features

• Atom extraction - Extract and filter the atom table
• Export/Import analysis - List module interfaces
• Bytecode disassembly - Human-readable assembly with opcode categorization
• Source interleaving - See source code alongside bytecode
• Call graph generation - Build DOT graphs of function calls
• Chunk inspection - Examine raw BEAM file structure
• Themeable output - Syntax highlighting with customizable themes

Installation

Add beam_spy to your list of dependencies in mix.exs:

def deps do
  [
    {:beam_spy, "~> 0.2.0"}
  ]
end

As a CLI tool

git clone https://github.com/QuinnWilton/beam_spy
cd beam_spy
mix deps.get && mix escript.build

This creates a beam_spy executable in the project directory.

Quick Start

# Show module metadata
./beam_spy info Enum

# List exported functions, filtered by name
./beam_spy exports lists --filter=map

# Disassemble with source interleaving
./beam_spy disasm GenServer -f "handle_call*" --source

# Generate a call graph as SVG
./beam_spy callgraph Enum --format=dot | dot -Tsvg -o graph.svg

Module Resolution

All commands accept either a file path or a module name:

# Module names (resolved automatically via code path)
./beam_spy info Enum           # Elixir module
./beam_spy info lists          # Erlang module
./beam_spy info GenServer      # Standard library

# Direct file paths
./beam_spy info ./my_module.beam
./beam_spy info /path/to/module.beam

Commands Reference

atoms

Extract the atom table from a BEAM file.

./beam_spy atoms Enum
./beam_spy atoms Enum --filter=map
./beam_spy atoms Enum --format=json

Options:

exports

List exported functions from a module.

./beam_spy exports lists
./beam_spy exports Enum --filter=map
./beam_spy exports Enum --plain    # One per line (for piping)

Options:

imports

List imported functions from a module.

./beam_spy imports GenServer
./beam_spy imports GenServer --group    # Group by module

Options:

info

Show module metadata.

./beam_spy info Enum

Output includes:

• Module name and source file
• Compile time and OTP version
• MD5 checksum and file size
• Count of chunks, exports, imports, atoms

chunks

List BEAM file chunks or dump raw chunk data.

./beam_spy chunks Enum               # List all chunks
./beam_spy chunks Enum --raw AtU8    # Hex dump of atom table

Options:

Common chunk IDs:

disasm

Disassemble BEAM bytecode into human-readable assembly.

./beam_spy disasm lists -f "reverse/1"
./beam_spy disasm Enum -f "map*" --source
./beam_spy disasm GenServer --format=json

Options:

Function filter patterns:

• map/2 - Exact match (name and arity)
• handle_* - Glob pattern
• map - Substring match

callgraph

Build a function call graph.

./beam_spy callgraph Enum
./beam_spy callgraph Enum --format=dot | dot -Tsvg -o graph.svg
./beam_spy callgraph Enum --format=json

Options:

Assembler Syntax Reference

The disasm command outputs BEAM bytecode in a human-readable assembler syntax. This section documents the syntax so you can understand the output.

Registers

BEAM uses several register types:

X registers are the primary working registers. x(0) through x(N-1) hold function arguments on entry. x(0) holds the return value.

Y registers are stack slots allocated with allocate. They persist across function calls and must be deallocated before returning.

Atoms

Atoms are displayed with Elixir-style colon prefix:

:ok
:error
:handle_call
Enum                  # Module atoms may omit the colon

External Function References

External function calls use the format :module:function/arity:

:erlang:error/1
:lists:reverse/2
Enum:map/2

Lists

Lists use square bracket notation:

[]                    # Empty list
[x(0), x(1)]         # List of registers
[:ok, x(0)]          # Mixed list

Map Operations

Map instructions use special syntax:

get_map_elements - Extract map values:

get_map_elements f(425), x(0), [step => x(5), last => x(4), first => x(3)]

put_map_assoc/put_map_exact - Create/update maps:

put_map_assoc f(0), x(1), x(2), 2, %{key: x(3), other: x(4)}

Allocation Tuples

Stack allocation uses compact notation:

alloc(w:2)           # Allocate 2 words
alloc(w:1, fn:1)     # 1 word + 1 fun slot
alloc(w:2, fl:1)     # 2 words + 1 float slot

Labels

Labels mark branch targets and function entry points:

  label 19:
  func_info :lists, :reverse, 1
  label 20:           # Entry point (from function header)
  test :is_nonempty_list, f(23), [x(0)]

The number in f(x) in test instructions refers to the label to jump to on failure.

Opcode Categories

BeamSpy categorizes opcodes for syntax highlighting:

Common Instruction Patterns

Function entry:

  label 19:
  func_info :lists, :reverse, 1    # Error info (called on pattern match failure)
  label 20:                         # Actual entry point

Type tests:

  test :is_nonempty_list, f(23), [x(0)]    # Test x(0), jump to label 23 on failure
  test :is_nil, f(21), [x(2)]
  test :is_eq_exact, f(425), [x(2), Range]

List operations:

  get_list x(0), x(1), x(2)    # x(1) = hd(x(0)), x(2) = tl(x(0))
  put_list x(1), [], x(1)      # x(1) = [x(1) | []]
  put_list x(0), x(1), x(0)    # x(0) = [x(0) | x(1)]

Stack management:

  allocate 4, 6                # Allocate 4 Y slots, preserve 6 X regs
  test_heap 4, 2               # Ensure 4 words heap space, preserve 2 X regs
  deallocate 1                 # Free 1 Y slot
  trim 3, 1                    # Remove 3 Y slots, keep 1

Function calls:

  call 2, {Enum, :map_range, 4}        # Local call
  call_ext 3, :Elixir.Enum:reduce/3    # External call
  call_only 2, {Enum, :"-map/2-...", 2} # Tail call (local)
  call_ext_only 2, :lists:reverse/2     # Tail call (external)

Example: lists:reverse/1

function reverse/1 (entry: 20)
────────────────────────────────────────────────────────
  line 15
  label 19:
  func_info :lists, :reverse, 1
  label 20:
  test :is_nonempty_list, f(23), [x(0)]
  get_list x(0), x(1), x(2)
  test :is_nonempty_list, f(22), [x(2)]
  get_list x(2), x(0), x(2)
  test :is_nil, f(21), [x(2)]
  test_heap 4, 2
  put_list x(1), [], x(1)
  put_list x(0), x(1), x(0)
  return
  label 21:
  test_heap 4, 3
  put_list x(1), [], x(1)
  put_list x(0), x(1), x(1)
  move x(2), x(0)
  line 16
  call_ext_only 2, :lists:reverse/2
  label 22:
  test :is_nil, f(19), [x(2)]
  return
  label 23:
  test :is_nil, f(19), [x(0)]
  return

This shows the optimized implementation:

• Labels 22, 23 handle edge cases (empty list, single element)
• Label 20 is the main entry point
• The function inlines the first two iterations of the loop for common cases
• Label 21 falls through to reverse/2 for lists longer than 2 elements

Source Interleaving

With --source, BeamSpy shows source code alongside bytecode:

function map/2 (entry: 420)
────────────────────────────────────────────────────────
1687 │ def map(enumerable, fun)
     │      label 419:
     │      func_info Enum, :map, 2
     │      label 420:
     │      test :is_list, f(421), [x(0)]
     │      call_only 2, {Enum, :"-map/2-lists^map/1-1-", 2}

Format:

• Line numbers appear in the left margin with a │ border
• Source lines are shown in italic (in supported terminals)
• Bytecode is indented under the corresponding source
• Line numbers are clickable hyperlinks in supported terminals

Distant references:

When bytecode references lines far from the current function (e.g., inlined code), BeamSpy shows a compact reference:

→ map_range (line 4539)
     │      call_fun 1

This indicates the bytecode came from the map_range function at line 4539.

Common Options

These options are available on all subcommands:

The --list-themes flag is available at the top level to list available themes.

Environment Variables

• NO_COLOR - Disable all color output when set (any value)

Output Formats

Most commands support multiple output formats:

• text (default) - Human-readable, styled with colors
• json - Machine-readable JSON
• dot - GraphViz DOT format (callgraph only)

./beam_spy exports Enum --format=json | jq '.[] | select(.arity == 2)'
./beam_spy callgraph Enum --format=dot | dot -Tpng -o graph.png

Themes

BeamSpy supports color themes defined in TOML format. Themes are stored in priv/themes/.

# List available themes
./beam_spy --list-themes

# Use a specific theme
./beam_spy disasm Enum --theme=monokai

Theme files define colors for:

• UI elements (headers, borders, keys)
• Data types (atoms, modules, functions, numbers)
• Opcode categories (call, control, data, etc.)
• Register types (x, y, fr)

License

MIT