/commands/bundler/bundle-outdated
bundle outdated: list Ruby gems with newer versions
- tool
- Bundler
- versions
- Bundler 2.x
- os
- any
bundle outdated compares the versions locked in Gemfile.lock with the newest versions available from your gem sources and lists every gem that is behind, with its Current, Latest and Requested versions and its Groups. It changes nothing. Narrow it with --only-explicit to see only the gems listed in the Gemfile, and with --filter-patch or --filter-minor to see only small updates; then update them with bundle update gemname.
Usage
bundle outdated # every outdated gem, direct and indirect
bundle outdated --only-explicit # only gems named in the Gemfile
bundle outdated rails # one gem
bundle outdated --group development # one Gemfile group
bundle outdated --filter-patch # only patch-level updates (also --filter-minor, --filter-major)
bundle outdated --filter-strict # only updates allowed by current constraints
bundle outdated --parseable # machine-readable lines (--porcelain)Run it from the folder with the Gemfile, or set BUNDLE_GEMFILE to point at it. Without network access, --local checks only gems already installed or cached.
Options
| Option | What it does |
|---|---|
| --only-explicit | Only gems listed in the Gemfile, not their dependencies |
| GEM [GEM...] | Check only the named gems |
| --group NAME / --groups | Filter by Gemfile group, or show results grouped by group |
| --filter-patch / --filter-minor / --filter-major | Only report updates at that level |
| --filter-strict, --strict | Only versions that the Gemfile and other gems allow |
| --pre | Also consider prerelease versions |
| --local | Do not contact the gem sources |
| --parseable, --porcelain | Output one gem per line for scripts |
Reading the result
A gem with a Requested constraint that excludes Latest (for example ~> 7.1.0 with latest 8.0.0) needs a Gemfile change before bundle update can reach it. A gem with no Requested value is an indirect dependency: it moves when the gem that needs it is updated. Gems that belong only to the development or test groups are lower risk to update than those in the default group.
Pitfalls
- Exit code. The command exits non-zero when anything is outdated, which can stop a script that runs with
set -e. - Missing gems. If the lock file lists gems that are not installed, Bundler may ask you to run
bundle installfirst; errors such as Could not find gem in locally installed gems come from that state. - Private sources. Gems from a private server or git source are checked against that source; without credentials the check fails for them.
- Updating everything. Do not answer a long list with plain
bundle update; update gem by gem with bundle update gemname --conservative and run the tests in between.
How to confirm it worked
After updates, run bundle outdated again: updated gems disappear from the list, and a fully current bundle prints that the bundle is up to date and exits with code 0.
FAQ
Why does bundle outdated exit with code 1?
Bundler exits non-zero when it finds outdated gems, so the command can fail a CI job. Use || true in scripts that only want the report.
What do the Current, Latest and Requested columns mean?
Current is the version in Gemfile.lock, Latest the newest available version, Requested the constraint from the Gemfile (empty when the gem is only a dependency), and Groups the Gemfile groups it belongs to.
How do I list only gems I can update without changing the Gemfile?
Add --filter-strict (or --strict). Bundler then only reports newer versions that satisfy the Gemfile constraints and the dependencies of other gems, which are the updates bundle update can do right away.