# rv: Ruby version and gem management with Rust-based tooling

> rv is a cross-platform Ruby environment and gem manager for developers who want command-scoped Ruby execution, project installs, isolated CLI tools, and shell-based version switching. It supports Ruby 3.2 through 4.0, but several broader gem-management features remain future plans.

**spinel-coop/rv** — 💎💨 Extremely fast Ruby version and gem manager

- Repository: https://github.com/spinel-coop/rv
- Website: https://rv.dev
- Stars: 1,811 · Forks: 55
- Language: Rust
- License: Apache-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/spinel-coop-rv

## Why rv combines Ruby runtimes and gem environments

rv addresses a practical gap between Ruby installation and dependency use. A machine can have Ruby available without having the correct project runtime, while installing gems into the wrong environment can produce version conflicts. rv groups several operations under one interface: selecting a Ruby version, installing the Ruby and gems required by a project, running a command with Ruby available, and placing gem command-line programs in isolated environments.

The intended audience is Ruby application developers, gem authors, and developers who work across several Ruby projects with different version requirements. The README explicitly supports Ruby 3.2, 3.3, 3.4, and 4.0. It also describes integration with zsh, bash, fish, Nushell, and PowerShell, plus support for macOS 14 or later, Linux with glibc 2.35 or later, and Windows 10 or later.

This is more than a runtime selector by name. The available commands cover several recurring tasks: `rv run` starts Ruby or a script, `rvx` invokes a gem CLI, `rv clean-install` installs a project's Ruby and gems from `Gemfile.lock`, and `rv tool install` installs a CLI into a dedicated environment. However, the feature boundary matters. Commands such as `rv sync`, `rv add`, `rv remove`, `rv gem new`, and `rv gem publish` appear under future features, not current usage instructions.

## rv's Rust workspace and command-specific environment model

The repository identifies Rust as its primary language, and `Cargo.toml` defines a Cargo workspace with separate crates for the executable and its domain areas. Listed members include `rv`, `rv-cache`, `rv-client`, `rv-lockfile`, `rv-gem-package`, `rv-gem-specification-yaml`, `rv-gem-types`, `rv-platform`, `rv-ruby`, `rv-version`, and `rv-dirs`. This layout indicates a division between the user-facing command layer, Ruby runtime handling, lockfile and gem data, platform detection, caching, networking, and version logic.

The user-facing behavior is command-scoped rather than tied to a single interactive model. `rv run [ruby|irb|myscript.rb]` runs a command or script with Ruby available. `rvx rails new .` exposes an installed gem command directly. `rv tool install rerun` places a tool CLI in a dedicated environment, which can prevent unrelated tools from sharing one gem namespace. For projects, `rv clean-install` reads the project's Ruby and gem requirements from `Gemfile.lock`.

Shell integration extends this model into the working directory. `rv shell [zsh|bash|fish|nu|powershell]` is documented as setting up automatic version switching, while `rv ruby pin 4.0.0` records a project Ruby selection. The repository links `docs/SHELL_INTEGRATION.md` for `.ruby-version` and automatic switching details, but the README does not describe the complete initialization or precedence behavior. Configuration can be stored in `rv.kdl` at project or user level, or supplied through environment variables prefixed with `RV_`. Detailed precedence rules are deferred to `docs/SETTINGS.md`.

## Installing rv and completing a first Ruby project use

On macOS or Linux, the README documents Homebrew as the first installation route. Homebrew installs the command but does not itself demonstrate that a compatible Ruby version or project dependencies are already available.

```bash
brew install rv
```

After installation, `rv --version` would be a natural verification command, but the README does not provide that command example, so it should not be treated as documented verification syntax. The first documented project operation is pinning Ruby 4.0.0. This selects the version associated with the project.

```bash
rv ruby pin 4.0.0
```

The next documented operation installs the project's Ruby and gems from `Gemfile.lock`.

```bash
rv clean-install
```

A reader should expect rv to consult the project's `Gemfile.lock` and install the corresponding supported Ruby and gem environment. The README does not document alternate registries, private credential configuration, lockfile editing, or rollback behavior.

For a one-off Ruby command rather than a complete project install, use the documented `rv run` syntax.

```bash
rv run irb
```

The Windows installer requires an elevated PowerShell session and uses a different command prefix because `rv` conflicts with the built-in `Remove-Variable` alias.

```powershell
powershell -ExecutionPolicy Bypass -c "irm https://rv.dev/install.ps1 | iex"
```

After installing on Windows PowerShell, substitute `rvw` for `rv` in documented commands.

## Running gem CLIs and separating tool environments

rv offers a direct interface for gem-provided commands. The README uses Rails application creation as its example:

```bash
rvx rails new .
```

This differs from first running a separate gem executable installer and then changing directories. `rvx` is presented as a way to run a gem command directly. The README does not explain how `rvx` resolves an uninstalled command, whether it installs it on demand, or how it handles executable name collisions. It would be unsafe to assume those details.

For repeated CLI use, `rv tool install` provides a separate installation path:

```bash
rv tool install rerun
```

The command is documented as installing CLI tools into dedicated environments. That separation can matter for developers who use tools that depend on incompatible gem versions, although the README does not document a command for listing installed tools, removing them, changing their Ruby versions, or inspecting their resolved dependencies.

The distinction between `rvx` and `rv tool install` is useful but not fully explained. The former is the short invocation path shown for a gem CLI. The latter explicitly creates a managed environment for a tool. Documentation for tool update and removal behavior would be necessary before treating `rv` as the sole authority for every command-line program in a development machine.

Shell integration adds a third path. It can select versions automatically from `.ruby-version`, but the full rules for nested directories, user defaults, and shell startup are contained in a separate document rather than the README.

## Platform limits and the current gem-management boundary

The requirements table creates concrete adoption boundaries. rv supports macOS 14+, Linux with glibc 2.35+, and Windows 10+. The documented CPU architectures are x86 and arm64. Projects using an older operating system, a non-glibc Linux distribution, or an unlisted Ruby release need another manager or a platform extension. Those releases are not supported by the stated requirements.

The larger limitation is that rv is not yet the all-in-one workflow implied by its ambition. The README says it is designed to handle the kinds of work associated with RVM, rbenv, chruby, asdf, mise, ruby-build, ruby-install, Bundler, and RubyGems. The current command list confirms runtime management, direct gem CLI execution, tool environments, clean project installation, version pinning, and shell integration. It does not yet confirm general dependency mutation or gem publishing. Those commands are listed under future features.

The README presents `bin/setup`, `bin/rv`, `bin/install`, `bin/test`, and `bin/lint` as the contributor workflow on macOS or Ubuntu, with equivalent PowerShell scripts under `bin\powershell\`. This indicates that source development has a distinct setup path from normal binary installation.

The performance claim is also carefully scoped. The README includes an image stating that rv installed Ruby 3.4.7 in 1.8 seconds and points to `docs/INSTALL_BENCHMARK.md`. It does not present those figures as universal results across systems, architectures, caches, or networks.

## rv versus Bundler, rbenv, RVM, and mise

The closest comparison is not simply rv versus a Ruby installer. Its scope overlaps several categories. The README describes rv as managing Ruby runtimes, gem CLIs, tool environments, project installs, and shell integration. It also lists Bundler, rbenv, RVM, and mise among the projects that inspired rv.

For an application repository whose team already has a stable Ruby and Bundler workflow, rv must justify replacement through operational consistency across runtimes and tools. For developers who juggle several Ruby versions, standalone gem CLIs, and shell-managed project selection, rv's command scope is more relevant. The decisive comparison would include behavior under existing `.ruby-version` files, private gem sources, unusual native gems, and CI environments, none of which are described in the README.

License terms are comparatively permissive. The repository metadata identifies Apache-2.0, while the README states that users may choose either Apache-2.0 or MIT. It also says contributions are dually licensed under those terms unless contributors explicitly state otherwise. Organizations still need to review the actual license files and contribution terms for their compliance process. The repository's last push was on 2026-10-15, and the recent release sequence includes v0.7.1 on 2026-09-24. Those dates indicate recent development activity, but the future-feature list shows that migration decisions should account for functional gaps rather than release cadence alone.

## Conclusion

Developers who want a single interface for installing supported Ruby versions, running Ruby in an explicit command context, and managing project dependencies may find rv worth adopting. Developers who need the README's future `rv sync`, `rv add`, `rv remove`, `rv gem new`, or `rv gem publish` workflows should wait for those features. Before replacing an existing manager, first verify support for the required Ruby version, operating system, shell, project lockfile, and preferred `rv` versus `rvw` command.

## FAQ

### How do I install rv on macOS or Linux?

The README documents `brew install rv` for macOS or Linux. It also documents a standalone installer script, while the GitHub releases page provides additional installation options and specific-version downloads.

### Why do I use rvw instead of rv on Windows PowerShell?

PowerShell already uses `rv` as an alias for the built-in `Remove-Variable`. The README therefore directs Windows PowerShell users to invoke rv commands with `rvw`.

### Which Ruby versions and shells does rv support?

The README lists Ruby 3.2, 3.3, 3.4, and 4.0. Supported shells are zsh, bash, fish, Nushell, and PowerShell.

### Can rv install a Rails application through the Rails gem?

Yes, the README shows `rvx rails new .` as a direct gem CLI invocation. It also documents `rv tool install NAME` for installing CLI tools into dedicated environments.

### Can rv add or remove gems from an existing project?

Not as a documented current command. The README places `rv sync`, `rv add`, and `rv remove` under future features; the current documented project command is `rv clean-install` from `Gemfile.lock`.

## Sources

- [License: Apache-2.0](https://github.com/spinel-coop/rv/blob/main/LICENSE)
- [Project website](https://rv.dev)
- [README](https://github.com/spinel-coop/rv/blob/main/README.md)
- [Releases](https://github.com/spinel-coop/rv/releases)
- [spinel-coop/rv on GitHub](https://github.com/spinel-coop/rv)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/spinel-coop-rv