rbenv-gemset and how one file per project pins your Ruby gems

Gemsets are sandboxes, and the file format is the whole point

rbenv-gemset plugs in to the goodness of rbenv, and brings you gem management that is at once simple, easy to understand and set up, with just one file with the simplest format ever.

The concept is that gemsets are sandboxed collections of gems. That lets you have multiple collections of, possibly customized, gems installed in different sandboxes, and specify, on a per-application basis, which sets of gems should be used.

The format is the part that makes it usable. In your application directory you create a file named `.rbenv-gemsets` containing the names of the gemsets you want to use, one per line or separated by whitespace, and the first gemset in the list is the primary gemset where new gems will be installed.

$ echo -e "my-gemset\nanother-gemset" > .rbenv-gemsets

That is the entire configuration surface for the common case. There is no manifest format, no versioned schema, no lockfile. A file with gemset names in it, and every gem command in that directory tree now operates on those sets.

The design goal is stated plainly in the project description, KISS yet powerful gem/set management for curious engineers and Ruby hackers with rbenv, and the readme is written for exactly that reader. It even points people who want to file a bug at how to ensure that you get help, linking the well known How To Ask Questions The Smart Way guide.

That is worth noting as a signal about the audience. This is a tool for people who are comfortable reading shell scripts and editing dotfiles, and the documentation assumes that.

The command set is small, and init is the entry point

Running `rbenv gemset` gives you the help output, and the list of possible commands is short: `active`, `create [version] [gemset]`, `delete [version] [gemset]`, `file`, `init [gemset]` and `list`, plus `version`.

The basic workflow is a short script:

cd my-project

# Set up a default gemset for your project.
# Also will create a `.rbenv-gemsets` file in the current directory.
# NOTE: this will create the gemset under the current ruby version.
rbenv gemset init

# Alternatively, you can provide `rbenv gemset init` with the name of a gemset:
rbenv gemset init [gemset]

# To create a gemset under a specific ruby version:
rbenv gemset create [version] [gemset]

# You can list the existing gemsets by using the following command:
# This should include the most recent gemset you just created.
rbenv gemset list

# You can delete a gemset with the following command:
rbenv gemset delete [version] [gemset]

So `init` is the command that matters, because it does two things at once: it creates the gemset and it writes the `.rbenv-gemsets` file into the current directory. Everything else in the set is maintenance.

The version argument on `create` and `delete` is the part that reveals the underlying model. A gemset belongs to a specific Ruby version, so the same project can have one gemset for Ruby 3.3 and another for 3.4 without the two sets of gems colliding. That is the reason a gemset is tied to a version at all, and it is also the reason the plugin has to look at the version when it decides where to install.

The `file` command is there for inspecting which gemset file is in effect, which is the answer to a question that comes up constantly once ancestor directory search is in play.

Project gemsets install into your checkout and vanish with it

The feature added in v0.4.0 is the one that changes how you work, and it is worth isolating from the rest.

To have gems install into a sub-folder in your project directory for easy removal later, with `rm -rf project_dir`, for editing or for testing, you can use a project gemset, and a project gemset has a `.` as the first character:

$ echo '.gems' > .rbenv-gemsets

Your gems then get installed in `project/.gems`. If you do not want to use a dot directory to house your gems but still want a project gemset, you can write `./gems` instead, and the gems will be installed in `project/gems`.

That is a genuinely different idea from the classic sandbox. A classic gemset lives in a shared location under rbenv and you activate it by name, and two projects using the same gemset share the same installed gems. A project gemset lives inside the checkout, so the gems are part of the project directory, and deleting the directory deletes the gems. That also means two checkouts of the same project can have different gems without interfering, which is what you want when one branch needs a different gem version.

The cost is disk and duplication. Every project with a project gemset carries its own copy of the gems, and the `.gems` directory ends up in your working tree, which means it needs to be in your ignore file.

The readme frames the benefit as three alternatives at once, easy cleanup later, easy customization, or testing, and that list maps neatly onto what a per-project directory gives you.

The search walks up to the filesystem root, so naming matters

There is a behaviour in this plugin that causes more confusion than anything else in it, and it is worth understanding before you install it.

The gemset plugin causes rbenv to search for the `.rbenv-gemsets` file in the current directory, as well as in all ancestor directories, until either a config file is found or it has gone all the way up to `/`. If, along the way, a `.ruby-gemset` file is found instead of `.rbenv-gemsets`, the `.ruby-gemset` file will be used.

So the effective configuration for a directory is determined by the nearest ancestor that has one of these files, and `/` counts. If you have a `.rbenv-gemsets` file somewhere high in your home directory, it will apply to everything below it, including directories you did not intend to configure. And a stale `.ruby-gemset` file takes precedence over a `.rbenv-gemsets` file in the same or an ancestor directory, which is a behaviour that dates from the project gemset plugin this one is descended from.

Two environment variables give you an escape hatch. `RBENV_GEMSETS` lets you work with a certain gemset, or a gemset list, and the readme gives a quick install into a certain gemset as the example, running `gem install thin` with `RBENV_GEMSETS` set to a named gemset. `RBENV_GEMSET_FILE` lets you point at the absolute path of a gemset file if you want to use one that is not in any of your ancestor directories, with the warning that you have to be using the same version of ruby for this to work as expected, and an example that sets it to a path under a home directory and runs `rails new`.

The `global` gemset is the other common point of confusion. To see your currently active gemsets, run `rbenv gemset active`, and the readme's advice is direct: if you do not have any actual gemset called `global`, forget about it, because `global` will not affect you at all. If you just do not like seeing it at the end, you can add a `-global`, a minus gemset, to your `.rbenv-gemsets` file.

Installation is a clone into the plugins directory, or a brew formula

There are two documented installation routes, and the GitHub one is a single command.

Download and extract the latest release, or clone rbenv-gemset to your `$HOME/.rbenv/plugins` directory, with the command `git clone https://github.com/jf/rbenv-gemset.git $HOME/.rbenv/plugins/rbenv-gemset`. The `bin/`, `etc/` and `libexec/` directories in the repository listing are the rbenv plugin layout, so the plugin goes in the plugins directory and rbenv picks it up from there.

For Homebrew on macOS, the route is `brew update` followed by `brew install rbenv-gemset`.

There is also a note for RubyMine users: RubyMine 8 now supports rbenv-gemset, with a link to the YouTrack issue describing it.

Once installed, the plugin needs no configuration file of its own. The `.rbenv-gemsets` file is per project, not per install, and the plugin reads it at the time a gem command runs. That is the design, and it is why the plugin needs no daemon, no background process and no state of its own beyond the sets it creates.

The version history in the repository is worth a look before you rely on it. Jamis Buck started the project in 2011, Joe Fiorini took over as maintainer in May 2012, and Jeffrey Lim took over in July 2013 and has maintained it since. The readme notes that the maintainer has been at it for over a decade and asks for sponsorship, and there is a special note for RubyMine users, so the project has a real history and a real user base.

The last push was on 2026-06-10 and the newest release is v0.5.102 from 2026-06-04, with v0.5.100 from 2025-09-07 before it, so releases come in bursts rather than on a calendar.

What a gemset does not solve, and when Bundler is the better tool

The honest comparison is with Bundler, and the difference is a layer.

A gemset is a directory of installed gems, scoped to a Ruby version. A Gemfile with a lockfile is a declarative description of exactly which gem versions a project needs, resolved and pinned. The first isolates installed state, the second specifies required state. They solve overlapping problems at different levels, and the overlap is where confusion comes from.

Where a gemset wins is when the requirement is loose. If you want to work on two projects that need different versions of a library and you do not want to think about resolution, a gemset per project gives you a clean separation with no manifest to maintain. It is also the right tool when you are experimenting with a gem's behaviour across versions, or when you want to install something without touching the global set of a Ruby you share with other work.

Where Bundler wins is everything about reproducibility, and that is a large part of what teams need. A lockfile gives you the same versions on every machine and in CI, and a `.rbenv-gemsets` file gives you a set of names with no version constraints at all. The gemset concept has no notion of a locked version, so two developers who create the same named gemset can end up with different gem versions inside it.

There is also a portability limit. Gemsets live under the rbenv directory tree, so they are tied to the machine and the rbenv installation. Bundler's vendor path and a checked in lockfile travel with the repository. For a team on CI, that difference is the whole argument.

So the practical rule is that a gemset is a convenience layer over an rbenv install, useful on one machine, while Bundler is the reproducibility layer, useful across machines. Most teams need the second and use the first as a supplement.

Editorial conclusion

rbenv-gemset fits a Ruby developer who runs several projects against the same rbenv installed Rubies and wants each project to declare which gem sets it uses, and it is a good fit for the project gemset form where gems install into a directory inside the checkout and disappear with it. It is the wrong choice if you already have every project on Bundler with a lockfile, because that solves the same problem at a better layer. Before adopting, verify three things: that the Ruby version you need is one rbenv can install, since a gemset is scoped to a version, that your project directory is one where a `.rbenv-gemsets` file is welcome, given the plugin searches ancestor directories all the way to `/`, and how you will handle the `global` gemset that shows up in the active list. The code is in the public domain, the last push was on 2026-06-10, and the newest release is v0.5.102 from 2026-06-04.

Frequently asked questions

Official sources

1. Issues
2. jf/rbenv-gemset on GitHub
3. README
4. Releases