BUNDLE-CACHE(1)

💅 BUNDLE-CACHE — the manual, but make it make sense

okay so bestie, you're looking at bundle-cache(1) from the General Commands Manual, and honestly? this one's a little gem (pun fully intended 🍓). let's get into it.

---

✨ NAME ✨

bundle-cache — package your needed .gem files into your application. that's it, that's the vibe. you're basically packing a little survival kit of gems and tucking it into your app so future-you never has to panic-download anything again 🎀

---

🦋 SYNOPSIS 🦋

bundle cache [OPTIONS]

and the aliases, because bundler loves a nickname era:

alias: package, pack

so bundle package and bundle pack are literally the same thing. iykyk 💅

---

💖 DESCRIPTION 💖

so what this does: it copies all of the .gem files you need to actually run the application into the vendor/cache directory. adorable, right?

and then in the future, when you run bundle install(1) bundle-install.1.html, it'll use the gems sitting in that cache in preference to the ones on rubygems.org. like, it checks its own purse before going shopping. iconic behavior tbh 🫶

---

🌸 OPTIONS 🌸

• --all-platforms — includes gems for all platforms present in the lockfile, not just the current one. so you're not just packing for yourself, you're packing for the whole group chat ✨
• --cache-path=CACHE-PATH — wanna put the cache somewhere other than the default vendor/cache? this is how. specify a different cache path, no cap.
• --gemfile=GEMFILE — use the gemfile you specify instead of Gemfile. for when your gemfile has a whole other name and identity, main character energy.
• --no-install — don't install the gems, just update the cache. cache only, no extra steps 💅
• --quiet — only output warnings and errors. silence, but make it useful 🤫

---

🧚 GIT AND PATH GEMS 🧚

plot twist: bundle cache can also package :git and :path dependencies, not just .gem files. so it's not just a gem-cacher, it's a whole dependency-cacher.

you can turn this off by setting cache_all to false. your call, bestie.

---

🌈 SUPPORT FOR MULTIPLE PLATFORMS 🌈

okay so this is the part where it gets a little technical but stay with me 🙈

when you're using gems that have different packages for different platforms, Bundler supports caching gems for other platforms — but only where the Gemfile has been resolved (i.e. present in the lockfile) — into vendor/cache.

this needs to be enabled via the --all-platforms option. and here's the cute part: this setting will be remembered in your local bundler configuration. it's giving "set it and forget it" 💜

---

🔥 REMOTE FETCHING 🔥

okay so by default, if you run bundle install(1) bundle-install.1.html after running bundle cache(1) bundle-cache.1.html, bundler will still connect to rubygems.org to check whether a platform-specific gem exists for any of the gems in vendor/cache. yes, even though you literally just cached them. it's thorough like that 😭

for instance, consider this Gemfile(5):

source "https://rubygems.org"

gem "nokogiri"

so if you run bundle cache under C Ruby, bundler will retrieve the version of nokogiri for the "ruby" platform. but if you deploy to JRuby and run bundle install, bundler is forced to check whether a "java" platformed nokogiri exists.

and like — even though the nokogiri gem for the Ruby platform is technically acceptable on JRuby, it has a C extension that does not run on JRuby. so as a result, bundler will, by default, still connect to rubygems.org to check whether it has a version of one of your gems more specific to your platform. rude? maybe. correct? yes 💀

and this problem is also not limited to the "java" platform. a similar (common) problem can happen when you're developing on Windows and deploying to Linux, or even when developing on OSX and deploying to Linux. so yeah, it's a whole situation.

so here's the move: if you know for sure that the gems packaged in vendor/cache are appropriate for the platform you're on, you can run bundle install --local to skip checking for more appropriate gems, and use the ones in vendor/cache. go off, no notes 👑

one way to be sure that you have the right platformed versions of all your gems is to run bundle cache on an identical machine and check in the gems. for instance, you can run bundle cache on an identical staging box during your staging process, and check in the vendor/cache before deploying to production. staging exists for a reason, bestie 🎀

and one more thing: by default, bundle cache(1) bundle-cache.1.html fetches and also installs the gems to the default location. but if you want to package the dependencies to vendor/cache without installing them to the local install location, you can run:

bundle cache --no-install

look at you, being all intentional about it ✨

---

⭐ HISTORY ⭐

a little lore for you: in Bundler 2.1, cache took in the functionalities of package, and now package and pack are aliases of cache. so if you were around in the before-times, that's where your old muscle memory went 🦋

---

okay that's the whole page, bestie — you're officially caught up 💖 this was BUNDLE-CACHE(1) from the General Commands Manual, dated April 2026. go cache those gems and slay 🎀💅✨