Format:RubyGems gem
| 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 theGem::Specification(name, version, files, executables,extensions,require_paths, dependencies,post_install_message). The reader also accepts an uncompressed entry namedmetadataand limits it to 10 MiB.data.tar.gz: gzipped tar of the files listed inspec.files, without a name-version prefix directory.checksums.yaml.gz: gzipped YAML mapping digest algorithm to{entry name: hex digest}formetadata.gzanddata.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 asmetadata.gz.sig,data.tar.gz.sigand so on (read, verified only when a security policy is set).- Verification fails if the spec or
data.tar.gzis 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