pockestrap

Programmer's memo

.ruby-version の歴史とその活用法

Programming Ruby

こんにちは。 id:Pocke です。最近はサトネちゃんのために働いています。1

この記事では.ruby-versionファイルの歴史を解説します。そして現代のRailsアプリケーション開発における.ruby-versionの扱い方を提案します。2

.ruby-version の歴史

まずは.ruby-versionがどのようにして使われるようになったのか、その歴史を見てみましょう。

.ruby-version前史

RubyにはRVMやrbenvなど複数のバージョンマネージャが存在します。これらのバージョンマネージャは.ruby-version以前から存在していました。

これらのバージョンマネージャは元々異なるファイルでRubyのバージョンを指定していました。例えばRVMは.rvmrc、rbenvは.rbenv-versionという具合です。

様々なツールが異なるファイルを使っていると、当然ながらツールの数だけファイルが増えていき、無駄な学習コストが発生してしまいます。

.ruby-versionの登場

そこで登場したのが、今回のテーマである.ruby-versionです。

各バージョンマネージャに共通のファイルとして、Rubyのバージョンだけが記述されたシンプルなファイルである.ruby-versionが提案され3、各ツールがそれを実装していきました。4

これが2012-2013年頃の出来事です。

.ruby-versionを利用するツールの拡大

このように.ruby-versionは当初バージョンマネージャが利用するファイルとして導入されました。ですがRubyのバージョンを指定したいツールはバージョンマネージャだけではありません。バージョンマネージャにおける.ruby-versionの普及に伴って、他のツールも.ruby-versionを利用するようになっていきました。

例えばRuboCopは2016年からTargetRubyVersionの自動検出に.ruby-versionを利用しています。5

またGitHub Actionsのruby/setup-rubyも2020年頃から、バージョンの指定がなければ.ruby-versionの値をデフォルト値として使っています。6

特にインパクトが大きいのはBundlerによるサポートです。 それまでもruby File.read(".ruby-version").stripのようにして.ruby-versionを読み取るテクニックはよく使われていました。これを公式にサポートする形で、ruby file: ".ruby-version"のようにRubyのバージョンを読み込むファイル名を指定する機能が2023年に導入されました。7 この機能により、.ruby-versionをよりスマートに利用できるようになりました。

この他にもRuby LSPなどのツールでも.ruby-versionを読み取る機能が実装されています。

このように、Rubyのバージョンを指定する多くのツールが.ruby-versionをデフォルトで参照しており、現代ではデファクトスタンダードになっていると言えるでしょう。

.ruby-versionの仕様策定

2023年頃からは.ruby-versionの仕様を策定する動きもあるようです。8

正式な決定には至っておらずドラフトが存在する段階ですが、これも.ruby-versionが様々なツールから利用されているがゆえの動きと言えるでしょう。9

.ruby-versionの扱い方

ここまでで.ruby-versionの歴史を解説しました。ここからは現代のRailsアプリケーションでの.ruby-versionの扱い方を提案します。10

Railsアプリケーション開発においては、Rubyのバージョン指定を.ruby-versionに集約するのが良いと考えています。

この利点はRubyのバージョンアップデートの負担が減ることです。RuboCopやGitHub Actionsなど様々なツールの設定ファイルにバージョン指定が散在しているとRubyのバージョンアップデートの際に手間がかかりますが、.ruby-versionに集約しておけばそこだけを更新すれば良くなります。

rbenvなどを使わない場合

一方、現代のRailsアプリケーション開発では、rbenvのようなバージョンマネージャが使われないケースが増えてきています。というのも、開発環境をDockerコンテナで構築し、その中でRubyのプロセスを動かすケースが多いためです。この場合RubyのバージョンはDockerイメージのタグで指定されるのが一般的であり、rbenvのようなバージョンマネージャの出番はなくなってしまいます。

ではそのようなケースでは.ruby-versionは不要なのでしょうか? 私はそうは思いません。

記事の前半で解説した通り、.ruby-versionはバージョンマネージャ以外のツールからも広く利用されているためです。rbenvなどを使う場合はもちろん、それらを使わない場合でも.ruby-versionを積極的に使っていくべきでしょう。

元々はrbenvなどのバージョンマネージャのために作られた.ruby-versionを、それらを使わない環境で使うのは少し不思議な感じもします。.ruby-versionが普及した結果と言えるでしょう。

.ruby-versionを直接サポートしないツール

.ruby-versionを直接サポートしないツールも存在します。例えばDockerfileではRubyのバージョンをベースイメージのタグとして指定しますが、Docker側は.ruby-versionを直接読み込むような機能は提供していません。

そのような場合、可能であれば.ruby-versionを利用するコードを追加するのが良いでしょう。例えばDockerfileの場合は以下のようにしてARG経由で.ruby-versionの内容を渡せます。

# Dockerfile
ARG RUBY_VERSION

FROM ruby:${RUBY_VERSION}-slim
# docker buildの実行
$ docker build --build-arg RUBY_VERSION="$(cat .ruby-version)" .

なお、.ruby-versionを直接サポートせず、そして.ruby-versionを利用しにくいツールにCircleCIがあります。.circleci/config.ymlの静的な値としてRubyのバージョンを指定する必要があるためです。 Dynamic configuration 11 という機能を使うと.ruby-versionを参照することも可能なようですが、設定が複雑になるため私は使ったことがなく、Rubyのバージョン指定が2箇所に重複することを許容しています。

まとめ

.ruby-versionの歴史と、現代のRailsアプリケーションにおける扱い方を解説しました。

.ruby-versionは元々バージョンマネージャのためのファイルとして登場しましたが、現在ではその手を離れ、様々なツールが利用するファイルへと進化しました。 バージョンマネージャのためだけではない、Rubyエコシステムのキーとなる要素の1つとして.ruby-versionを積極的に活用すると良いでしょう。

  1. Chill with You は最高のポモドーロタイマーです。 https://commits.hatenablog.com/entry/2025/12/11/100000↩
  2. 類似のファイルとして.tool-versionsなども存在します。.ruby-versionが一番広く使われているためおすすめですが、この記事で紹介するツールの多くは.tool-versionsなどもサポートしているため、そちらを使う選択肢もあるでしょう。↩
  3. https://gist.github.com/fnichol/1912050↩
  4. https://github.com/rbenv/rbenv/pull/302 https://github.com/rvm/rvm/issues/786 https://github.com/postmodern/chruby/issues/30↩
  5. https://github.com/rubocop/rubocop/pull/3228↩
  6. https://github.com/ruby/setup-ruby/commit/a61be15bffe8c2671699ce4b4eb6e7c8f2ce3f4d↩
  7. https://github.com/ruby/rubygems/pull/6876↩
  8. https://github.com/ruby/rubygems/discussions/7074↩
  9. https://github.com/dot-ruby-version/specification↩
  10. gemなどのライブラリ開発の場合は複数のRubyのバージョンをサポートする事が多いため、Railsアプリとは異なり.ruby-versionを使うことは少ないでしょう。↩
  11. https://circleci.com/docs/guides/orchestrate/dynamic-config/↩