libyear-rb

A measure of dependency freshness for Gemfile.lock. Tells you how out-of-date your dependencies are, in libyears by comparing the release date of the locked version to the latest available version.

To use the CLI, install the gem:

gem install libyear-rb

mise install gem:libyear-rb

To use programmatically, add to your Gemfile:

gem "libyear-rb"

require "bundler/inline"
gemfile do
  source "https://rubygems.org"
  gem "libyear-rb"
end

Run libyear-rb in a directory with a Gemfile.lock, or provide a path:

libyear-rb                      # Uses ./Gemfile.lock
libyear-rb path/to/Gemfile.lock # Uses specified lockfile

Gem                  Current Current Date Latest   Latest Date Versions Days Years
.................... ....... ............ ........ ........... ........ .... .....
addressable          2.8.7   2024-06-21   2.8.8    2025-11-25         1  522  1.43
bigdecimal           3.3.1   2025-10-09   4.0.1    2025-12-17         4   69  0.19
rails                7.0.0   2021-12-15   7.2.0    2024-08-10        15  968  2.65
System is 4.27 libyears behind
Total releases behind: 20

Options:

--as-of DATE        Only consider versions released before DATE (YYYY-MM-DD)
--format FORMATTER  Choose an output formatter (plaintext, json)
--verbose           Run with logs
--help              Show help
--version           Show version

• plaintext (default) — prints a human-readable table to stdout, listing only outdated gems.
• json — prints a machine-readable JSON document to stdout, listing every gem along with a summary.

libyear-rb --format json

require "libyear_rb"

results = LibyearRb::Runner.new.run(File.read("Gemfile.lock"))

results.each do |r|
  puts "#{r.name}: #{r.version_distance} versions, #{r.libyear_in_days} days behind"
end

Configure the cache or logger before use:

LibyearRb.cache = LibyearRb::FileCache.new(skip_cache: true)
LibyearRb.logger = Logger.new($stderr)

libyear-rb supports any gem server with a RubyGems.org-compatible API. It uses your configured gem sources from ~/.gemrc (gem sources) or environment, so private gems hosted on servers like Gemfury, Artifactory, or self-hosted solutions work automatically.

To reduce API requests and improve performance, libyear-rb caches gem version metadata for 24 hours.

Cache location:

• Gem info is cached under $XDG_CACHE_HOME/libyear-rb/ (or ~/.cache/libyear-rb/ if XDG_CACHE_HOME is not set), with a subdirectory for each gem host.

To skip the cache:

SKIP_CACHE=1 libyear-rb

To clear the cache:

rm -rf ~/.cache/libyear-rb

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests.

# Setup development environment
bin/setup

# Run tests
rake test

# Run linter
rake rubocop

# Install gem locally
bundle exec rake install

The concept of libyear comes from the technical report "Measuring Dependency Freshness in Software Systems" by J. Cox, E. Bouwers, M. van Eekelen and J. Visser (ICSE 2015).

• libyear-bundler - The original Ruby libyear implementation. Supports additional metrics like major/minor/patch version deltas and JSON output.
• bundler-audit - Focuses on security vulnerabilities rather than freshness.
• bundle outdated - Built into Bundler. Shows outdated gems but doesn't calculate libyears.

The gem is available as open source under the terms of the MIT License.