Jump to content
Setting up an AI agent? ReverseEngineering.wiki skill (works from the command line, no configuration): https://reverseengineering.wiki/skill/rewiki/SKILL.md · setup for every client, including MCP: https://reverseengineering.wiki/llms.txt · REWiki:Connect

Format:RubyGems gem

From ReverseEngineering.wiki
Format
Magic tar (ustar magic at offset 257); first entry usually metadata.gz
Extensions .gem
On this wiki Facts · Code · Notes · Topics

RubyGems package (.gem): an uncompressed tar holding metadata.gz (gzipped YAML Gem::Specification), data.tar.gz (the files) and checksums.yaml.gz, with optional .sig signature entries; native extensions listed in the spec are compiled at install.

A .gem file is a plain tar archive (not compressed as a whole). Per the comment at the top of lib/rubygems/package.rb, it contains data.tar.gz, metadata.gz, checksums.yaml.gz and possibly signatures. Gem::Package#build writes the entries in this order: metadata.gz, data.tar.gz, checksums.yaml.gz, each with mode 0444.

Entries

  • metadata.gz: gzip of the YAML dump of the Gem::Specification (name, version, files, executables, extensions, require_paths, dependencies, post_install_message). The reader also accepts an uncompressed entry named metadata and limits it to 10 MiB.
  • data.tar.gz: gzipped tar of the files listed in spec.files, without a name-version prefix directory.
  • checksums.yaml.gz: gzipped YAML mapping digest algorithm to {entry name: hex digest} for metadata.gz and data.tar.gz; the writer always computes SHA512 in addition to the signer's algorithm. Reading verifies each listed digest and raises a FormatError on mismatch; entries without a recorded checksum are ignored.
  • <entry>.sig: when the author has a signing key, a signature of the entry's digest is added as metadata.gz.sig, data.tar.gz.sig and so on (read, verified only when a security policy is set).
  • Verification fails if the spec or data.tar.gz is missing or if an entry name occurs twice.

Recent RubyGems can also write a content-addressed file name, name-version-<8 hex chars of the SHA-256 digest>.gem, derived from the gem bytes (build_content_addressable_file).

Where code runs at install

Gem::Installer#install extracts the files, then calls build_extensions. For each entry in the spec's extensions list the builder is chosen by file name: extconf (ExtConfBuilder, runs the Ruby script extconf.rb that generates a Makefile), configure, Rakefile or mkrf_conf, CMakeLists.txt, or Cargo.toml (CargoBuilder). Those scripts are package code that runs at install; the install also runs pre/post install hooks registered by plugins and can load rubygems plugins (rubygems_plugin.rb) from the gem (Unverified: the plugin file name and when it loads; the installer's generate_plugins and load_plugin calls were seen but not read). Installing with extension building disabled prints a warning and gem pristine <name> --extensions builds them later.

Unpacking

tar xf name.gem then gunzip metadata.gz and tar xzf data.tar.gz is enough to read a gem. The repository moved to github.com/ruby/rubygems.

Code & repositories

  • https://github.com/ruby/rubygems @ f033df93676007227d1ae0bd7326008e6396b3e9 · license: MIT (declared by the contributor; GitHub's detector did not recognize LICENSE.txt)
    RubyGems: lib/rubygems/package.rb (gem tar layout), installer.rb and ext/builder.rb (extension builds).
    Tested on: source read, not run · checked 2026-10-19; last activity 2026-10-15; Note: the latest release ships binaries; the wiki links only the source, never the binaries

See also

Technique:Install-time code execution in package archives.