Platforms and native gems

How RubyGems names the system a gem was built for, and how precompiled native gems skip compilation at install time.

Most gems are pure Ruby and install identically everywhere. Gems that include native extensions compile C or Rust code during installation, and many of them also publish precompiled binaries so that on common systems nothing is compiled at all. This page explains what a gem platform is, how the matching variant is chosen at install time, how platforms interact with Gemfile.lock, and how to force the source build when a binary does not suit you.

What a gem platform is

Every published gem carries a platform. The platform ruby means the gem is delivered as source and installs on any system. Gems whose extensions are compiled on your machine at install time are ruby platform gems too. A concrete platform names the CPU architecture and operating system a prebuilt binary targets, such as x86_64-linux-gnu, arm64-darwin, or x64-mingw-ucrt, and the platform java marks builds for JRuby.

Your machine has a local platform, derived from your Ruby’s build configuration:

$ gem env platform
ruby:arm64-darwin-27

The output lists the platforms RubyGems will install on this machine, ruby plus the local platform. The local platform is also available in code as Gem::Platform.local. A gem is only considered for installation when its platform matches one of these. The full matching rules are described in gem help platform.

Precompiled native gems

A gem that ships precompiled binaries publishes the same version number several times, once per platform. For example, nokogiri 1.19.4 exists on RubyGems.org as the source ruby gem, a java build, arm64-darwin and x86_64-darwin builds for macOS, an x64-mingw-ucrt build for Windows, and Linux builds for three CPU architectures in both -gnu and -musl variants.

You do not choose among them. gem install and bundle install pick the variant matching your local platform automatically, and fall back to the ruby gem when no binary matches. You can watch the choice with gem fetch, which downloads a gem without installing it:

$ gem fetch nokogiri
Downloaded nokogiri-1.19.4-arm64-darwin

When a binary matches, installation is fast and needs no compiler. When only the ruby gem matches, the extension is compiled on your machine, which requires a working toolchain and the libraries the gem wraps. If that build fails, see Troubleshooting. If you maintain a gem with an extension and want to publish your own precompiled binaries, see Gems with Extensions.

Linux and musl

Linux platform names end with the C library the binary was linked against. x86_64-linux-gnu targets glibc systems, which covers most distributions, and x86_64-linux-musl targets musl systems such as Alpine. A -gnu binary is never selected on a musl system. If a gem publishes no -musl build, a musl system falls back to the ruby gem and compiles the extension.

Older gem releases used the bare name x86_64-linux instead. A bare Linux platform matches both glibc and musl systems, so such a binary installs on Alpine whether or not it can actually run there. If a precompiled gem installs but fails to load, force the source build as described below.

Platforms in Gemfile.lock

Bundler records the platforms a resolution covers in the PLATFORMS section of Gemfile.lock and locks the platform-specific gem versions for each. A fresh Bundler 4 lockfile for an application depending on nokogiri covers every platform the precompiled builds support:

PLATFORMS
  aarch64-linux-gnu
  aarch64-linux-musl
  arm-linux-gnu
  arm-linux-musl
  arm64-darwin
  x86_64-darwin
  x86_64-linux-gnu
  x86_64-linux-musl

Installing on a platform the lockfile does not cover normally just works. Bundler adds the local platform, re-resolves, and updates the lockfile. In CI and production the lockfile is typically frozen, so the same situation fails instead. This is the classic error when an application is developed on macOS with an older lockfile and deployed to Linux:

Your bundle only supports platforms ["arm64-darwin-27"] but your local platform
is x86_64-linux. Add the current platform to the lockfile with
`bundle lock --add-platform x86_64-linux` and try again.

The fix is what the message says. Run bundle lock --add-platform x86_64-linux on your development machine, commit the updated lockfile, and deploy again. The error only occurs when the PLATFORMS section contains neither your platform nor ruby, which is why it usually involves precompiled native gems. Rather than adding platforms one by one, run bundle lock --normalize-platforms before committing. One run adds every platform your locked gems are precompiled for, and it also strips the OS version from entries like arm64-darwin-27 so that lockfiles generated on different machines agree. How Gemfile.lock works covers when to run it, and bundle lock documents the command.

Despite the name, the platforms block in a Gemfile is a different concept. Its values, such as ruby, windows, and jruby, group dependencies by Ruby implementation rather than naming lockfile platforms. See the Gemfile reference.

Forcing the source build

Sometimes the precompiled binary is the wrong choice. It may misbehave on your system, or its required_ruby_version may exclude a Ruby that the source gem still supports. The force_ruby_platform setting tells Bundler to ignore your machine’s platform, install only ruby platform gems, and compile native extensions from source:

bundle config set --local force_ruby_platform true

To force the source build for a single gem, set the option in the Gemfile:

gem "ffi", force_ruby_platform: true

With plain gem install, pick the platform explicitly instead:

gem install nokogiri --platform ruby

See the force_ruby_platform entries in bundle config and the Gemfile reference.