How to evaluate a Rails gem before adding it to your Gemfile
Adding a line to the Gemfile takes seconds; removing a gem that has spread through a codebase can take weeks. This checklist is what we go through before recommending a gem, and what we suggest you run through before depending on one.
1. Do you need a gem at all?
Rails now covers ground that used to require third-party code. Before searching RubyGems, check the framework: Active Storage for attachments, Active Job with Solid Queue for background work, has_secure_password and the Rails 8 authentication generator for logins, Action Text for rich text, encrypted attributes in Active Record, and Solid Cache for caching. The Rails Guides are the fastest way to find out. Built-in features follow the framework's release and security process, which no single gem can match.
Also consider the size of the problem. A gem that saves you twenty lines of code still brings its own dependencies, upgrade cycle and possible security issues. For small helpers, writing the code yourself is often the better trade.
2. Maintenance signals
A gem's page on RubyGems.org shows its release history, and the JSON API (https://rubygems.org/api/v1/gems/NAME.json) gives the latest version and its date. Look at:
- Release cadence. Regular releases, including releases soon after each new Rails version, are the strongest positive signal. A library with no release in several years may still work, but you should assume you will be the one fixing it.
- The repository. Is it archived? Does the README carry a deprecation notice? Thoughtbot's Paperclip, for instance, announced its deprecation in its README long before the repository was frozen (see our note on Paperclip).
- Continuous integration. A CI matrix that tests against the Ruby and Rails versions you use is better evidence than any badge count. Look for the matrix in
.github/workflowsor the equivalent. - Issue and pull request handling. You are not looking for zero open issues, but for evidence that maintainers respond, label, and close or merge within a reasonable time.
- Bus factor. A gem maintained by one volunteer is not a problem in itself; many excellent gems are. It is a reason to keep your usage of it contained so that it can be replaced.
3. Compatibility with your Rails and Ruby versions
Open the gemspec, or the "Runtime Dependencies" section on RubyGems.org. A declaration such as add_dependency "railties", ">= 7.1" tells you the lower bound; an upper bound such as "< 8.0" will block your next upgrade until the maintainers release a new version. Check the declared required_ruby_version too.
The Rails team publishes its maintenance policy, which says which release series receive bug fixes and security fixes. A gem that only supports unmaintained Rails series will hold your application back on an unsupported framework.
Some compatibility problems do not show up in the gemspec:
- Autoloading. Since Rails 7.0, applications use the Zeitwerk autoloader exclusively. Engines and gems that rely on the old classic autoloader conventions can break in subtle ways; the autoloading guide explains the rules.
- Monkey patches. Gems that reopen Active Record or Action Pack internals tend to break on minor releases. Search the source for
class ActiveRecord::orprependon framework classes. - Database adapters. Some gems only support PostgreSQL, or only MySQL. Pg_search, for instance, is PostgreSQL only by design.
4. Dependencies and footprint
Run bundle add NAME in a branch and inspect the diff of Gemfile.lock. Every new line is another gem that can have vulnerabilities, version conflicts or abandoned maintainers. bundle info NAME and gem dependency NAME show what a gem pulls in. Prefer gems with few runtime dependencies, and be wary of gems that require native extensions you do not otherwise need, as they complicate Docker builds and deployments.
5. Licence
Most Rails gems use the MIT licence, but not all. Sidekiq and Avo are published under the LGPL-3.0, with commercial editions sold separately; Brakeman uses its own public-use licence; bundler-audit is GPL-3.0-or-later as a tool, which does not affect your application since it is not loaded into it. The licence field on RubyGems.org is a starting point; the LICENSE file in the repository is the reference.
6. Security history and advisories
Known vulnerabilities in Ruby gems are collected in the Ruby Advisory Database and in the GitHub Advisory Database. bundler-audit checks your Gemfile.lock against the former:
gem install bundler-audit bundle-audit check --update
The --update flag refreshes the local copy of the advisory database before checking. Run it in CI so that a new advisory fails the build rather than waiting for someone to notice. Dependabot or a similar service can open pull requests for vulnerable versions automatically.
A past advisory is not a reason to reject a gem; how it was handled is what matters. Look for a prompt patched release, a clear changelog entry and backports to older supported versions.
For your own code, Brakeman performs static analysis of a Rails application for issues such as SQL injection and unsafe redirects. New Rails applications generated with Rails 7.2 or later include Brakeman and a CI workflow that runs it, together with RuboCop.
7. Supply-chain hygiene
RubyGems.org lets gem owners require multi-factor authentication for publishing, shown on the gem page through the rubygems_mfa_required metadata. It is a useful, if partial, signal that an account takeover cannot silently push a malicious release. Beyond that:
- Check the gem name carefully; typosquatting packages imitate popular names.
- Commit
Gemfile.lockfor applications, and review lockfile diffs in pull requests. - Use pessimistic constraints such as
gem "pagy", "~> 43.0"when a gem has a history of breaking changes between major versions, and read the changelog before raising the bound.
8. Exit cost
Finally, imagine removing the gem in two years. Gems that you call from a few well-defined places (a job adapter, an uploader class, a policy object) are cheap to replace. Gems that add methods to every model, change routing globally or generate views you then customise heavily are expensive. Wrapping a dependency behind your own small interface is often worth it for the second kind.
A short checklist
| Question | Where to look |
|---|---|
| Does Rails already do this? | Rails Guides |
| Released recently, and after the latest Rails? | RubyGems.org versions page |
| Supports my Rails and Ruby versions? | Gemspec, CI matrix |
| Archived or deprecated? | Repository, README |
| What does it pull in? | Gemfile.lock diff |
| Licence acceptable? | LICENSE file |
| Known advisories? | bundle-audit check --update |
| How hard to remove later? | Your own design |
The category guides apply this checklist to the most common jobs in a Rails application.
GuidesFrom plugins to engines
How Rails extensions moved from vendor/plugins to gems, Railties and engines between Rails 2 and Rails 4, and what that means when you read old tutorials or upgrade an old app.
Category guidesAuthentication
Comparing Rails authentication options in 2026: the Rails 8 authentication generator, Devise, Rodauth, Authlogic, Clearance and Sorcery, plus OmniAuth for social login.
Category guidesBackground jobs
How to choose a background job backend for Rails: Active Job, Solid Queue (the Rails 8 default), Sidekiq, GoodJob, delayed_job and Resque, and what replaced Workling and Spawn.