/flags/bundler/bundle-lock-add-platform
bundle lock --add-platform x86_64-linux: support CI and Docker platforms
- tool
- Bundler
- command
- bundle lock
- flag
- --add-platform PLATFORMS, --remove-platform PLATFORMS, --normalize-platforms
- default
- only the platform of the machine that resolved the lockfile (plus generic ruby in some versions)
Gemfile.lock lists the platforms it was resolved for in its PLATFORMS section, and for gems that ship precompiled native builds (nokogiri, ffi, grpc, sass-embedded, google-protobuf) it records one entry per platform. A lockfile created on a Mac therefore often knows only arm64-darwin. bundle lock --add-platform x86_64-linux re-resolves the bundle for Linux too, without needing a Linux machine, so CI and Docker builds that install with a frozen lockfile find the right gems.
Commands
bundle lock --add-platform x86_64-linux # most servers and CI runners
bundle lock --add-platform x86_64-linux aarch64-linux # several at once
bundle lock --add-platform x86_64-linux-musl # Alpine-based images
bundle lock --remove-platform x86_64-darwin # drop an unused one
git add Gemfile.lock && git commit -m "Lock for Linux"After the command, the PLATFORMS section of Gemfile.lock lists the new platform, and platform-specific gems get extra entries such as nokogiri (1.x.y-x86_64-linux-gnu).
Common platform names
| Platform | Machines |
|---|---|
| x86_64-linux | Linux on Intel/AMD with glibc (Debian, Ubuntu, most CI runners) |
| aarch64-linux | Linux on ARM64 (Graviton, Docker on Apple Silicon) |
| x86_64-linux-musl / aarch64-linux-musl | Alpine Linux images |
| arm64-darwin | macOS on Apple Silicon |
| x86_64-darwin | macOS on Intel |
| x64-mingw-ucrt | Windows with Ruby 3.1 and later |
| ruby | Generic: gems compiled from source on install |
ruby -e 'puts Gem::Platform.local' prints the platform of the current machine, useful to check what a CI image reports.
Why frozen installs need it
In deployment or frozen mode, Bundler may not change Gemfile.lock. If the lockfile has no entry for the current platform, it cannot add one and the install fails, typically with a message that the bundle does not support the current platform and that bundle lock --add-platform should be run, or with gems missing as in Could not find gem in locally installed gems. Frozen and deployment settings are covered in bundle install --deployment.
Pitfalls
- Adding a platform resolves again and may need network access to fetch the platform-specific gem metadata.
- Precompiled gems for a platform must exist for the locked version; if not, Bundler falls back to the
rubyplatform gem, which compiles on install and needs build tools in the image. force_ruby_platform(BUNDLE_FORCE_RUBY_PLATFORM=true) ignores platform builds completely and always compiles; it is a workaround for broken precompiled gems, not a replacement for the right platforms.--normalize-platformscleans up platform lists in old lockfiles that mix generic and specific entries.
FAQ
Why does my Gemfile.lock work on my Mac but fail in Docker?
Bundler records the platforms the lockfile was resolved for in the PLATFORMS section. A lockfile created on macOS may list only arm64-darwin, so a frozen install on Linux has no matching platform-specific gems (nokogiri, grpc, sass-embedded). Add the Linux platform with bundle lock --add-platform x86_64-linux and commit the lockfile.
Which platform names should I add?
The ones of the machines that install the bundle: x86_64-linux for most servers and CI, aarch64-linux for ARM servers and Docker on Apple Silicon, and the musl variants (x86_64-linux-musl) for Alpine images. ruby is the generic platform for gems without precompiled builds.
How do I remove a platform again?
Run bundle lock --remove-platform NAME. Bundler drops the platform from PLATFORMS and the platform-specific gem entries that only it needed.