rbenvでrubyのバージョンを3.2.0に変更した時の障害と対応方法
Redmine Advent Calendar 2025
今回の記事は下記の「Redmine Advent Calendar 2025」の12/4の記事として作成しました。
急に寒くなり今年も残り数日です。今年もRedmine Advent Calendarの時期になりました。Advent Calendarに参加してRedmine界隈を盛り上げていけたらと思っています。
誰かの役に立てたら嬉しいなと思います。
現状と目標
ruby -v
ruby 2.6.6p146 (2020-03-31 revision 67876) [x86_64-darwin21]
現在の環境はruby -vで確認をすると、上記のように現在のrubyバージョンは2.6.6の環境です。
Redmine6.1.0をインストールするためにruby3.2.0をインストールする。
実行内容
rbenv install 3.2.0
rbenv versions
system
* 2.6.6 (set by /Users/xxx/redmine/.ruby-version)
2.7.1
2.7.8
3.2.0
rbenv install 3.2.0を実行してrbenv versions で確認をすると無事に3.2.0がインストールされた。
課題
rbenv rehash
rbenv local 3.2.0
ruby -v
ruby 2.6.6p146 (2020-03-31 revision 67876) [x86_64-darwin21]
ローカルフォルダーで3.2.0を使うためにrbenv rehash、rbenv local 3.2.0をしてruby -v でバージョンを確認したが3.2.0ではなく2.6.6のままであった。
原因
(set by /Users/xxx/redmine/.ruby-version)
rbenv versions の出力には、2.6.6 の横に (set by /Users/xxx/redmine/.ruby-version) という記述がある。
rbenvがバージョンを決定する際に、現在のディレクトリに .ruby-version ファイルが作成され、3.2.0 が指定されているが、現在のディレクトリ (/Users/xxx/redmine-6.1.0) を超えて、その親ディレクトリ (/Users/xxx/redmine) に存在する .ruby-version ファイルを見つけ、それが 2.6.6 を指しているため、それが優先されていたことを意味する。
本来であればrbenvは、カレントディレクトリからルートディレクトリに向かって .ruby-version ファイルを探し、最初に見つけたものを優先するため、現在のディレクトリ (/Users/xxx/redmine-6.1.0) の.ruby-version ファイルを参照するはずだが、何らかの理由で親ディレクトリ (/Users/xxx/redmine) に存在する .ruby-version ファイルを参照していた。そのためrbenv local 3.2.0の設定が反映されなかった。
対応策
rbenv local --unset
親ディレクトリ (/Users/xxx/redmine) でrbenv local --unsetを実行して.ruby-version ファイルを削除した。
結果
rbenv local 3.2.0
ruby -v
ruby 3.2.0 (2022-12-25 revision a528908271) [x86_64-darwin21]
上記のように無事に3.2.0のruby環境を構築できた。
次回の記事でRedmine6.1.0のインストール方法を説明する。
参考
下記は上記の内容をAIに与えてリライトをしてもらった内容です。すごい時代だなと素直に思います。
🚀 rbenvでRubyバージョンを変更できない問題の解決と仕組み
Redmine 6.1.0のインストールに向けて、rbenvでRuby 3.2.0をインストールし、ローカルディレクトリに適用する際、設定が反映されないという問題に直面しました。これは、rbenvのバージョン探索ロジックとディレクトリ構造が原因で発生する、非常によくあるケースです。
1. 🛠️ 前提条件と実行内容
| 項目 | 詳細 |
|---|---|
| 目標 | Redmine 6.1.0 のために Ruby 3.2.0 をローカルディレクトリに適用する。 |
| 現在のディレクトリ | /Users/xxx/redmine-6.1.0 |
| 親ディレクトリ | /Users/xxx/redmine |
| インストール済みバージョン |
system, 2.6.6, 2.7.1, 2.7.8, 3.2.0
|
実行したコマンドと課題
Ruby 3.2.0のインストールは成功したものの、バージョン切り替えに失敗しました。
# バージョンをローカルに設定
rbenv local 3.2.0
# 結果を確認
ruby -v
# => ruby 2.6.6p146 (3.2.0ではなく2.6.6が適用された)
2. 🛑 原因：rbenvの探索ロジックと競合
技術的根拠となった出力
バージョンが2.6.6に固定されていた原因は、rbenv versions の出力に明確に示されていました。
* 2.6.6 (set by /Users/xxx/redmine/.ruby-version)
rbenvは、カレントディレクトリからルートディレクトリ (/) へ向かって .ruby-version ファイルを探し、最初に見つけたものを優先します。
-
カレントディレクトリ (
redmine-6.1.0):rbenv local 3.2.0により3.2.0が設定されている。 -
親ディレクトリ (
redmine):2.6.6が設定されているファイル (/Users/xxx/redmine/.ruby-version) が存在する。
なぜ親ディレクトリが優先されたのか？（補足）
本来、rbenvはまずカレントディレクトリの .ruby-version (3.2.0) を参照するはずです。しかし、このケースで親ディレクトリの設定が有効になった原因は、以下のいずれかである可能性が高いです。
-
シェルのキャッシュ:
rbenv rehashやrbenv localの実行タイミングと、シェルの設定ファイルの読み込みのタイミングにより、新しい設定が反映される前に親ディレクトリの設定がキャッシュされていた。 -
探索の誤認: ターミナルが、実際には意図せず親ディレクトリ (
/Users/xxx/redmine) でRubyコマンドを実行しようとしていた。
重要なのは、rbenv versions の出力が示す通り、rbenvが最終的に 2.6.6 の設定ファイルを適用したという事実です。
3. ✅ 対応策と成功
実行した対応策
影響を与えていた親ディレクトリの設定ファイルを削除することで、競合を解消しました。
-
親ディレクトリ (
/Users/xxx/redmine) に移動し、設定ファイルを削除。rbenv local --unset # これにより /Users/xxx/redmine/.ruby-version が削除されました。 -
カレントディレクトリ (
redmine-6.1.0) に戻り、3.2.0を再設定。
結果
rbenv local 3.2.0
ruby -v
# => ruby 3.2.0 (2022-12-25 revision a528908271) [x86_64-darwin21]
これで無事に Ruby 3.2.0 環境の構築に成功し、Redmine 6.1.0のインストールに進めるようになりました。
4. 📝 今後の再発防止策
rbenvを安定して利用するために、以下のポイントを習慣づけることをお勧めします。
1. バージョン設定はカレントディレクトリでのみ行う
バージョン設定は、最も深いプロジェクトのルートディレクトリでのみ行うようにし、親ディレクトリに曖昧な .ruby-version ファイルを残さないようにしましょう。
2. rbenv rehash の実行
Gemのインストール後やRubyバージョンの変更後は、必ず rbenv rehash を実行し、rbenvの**シム（Shim）**と呼ばれる実行ファイルのラッパーを更新してください。
💡 rbenvのシムとは？
rbenvは、rubyやgemコマンドを直接実行せず、その代わりに「シム」という軽量なラッパーファイルを実行します。このシムが、カレントディレクトリの設定 (.ruby-version) を読み取り、適切なバージョンの実際のruby実行ファイルに処理を渡します。rehashはこのシムを最新の状態に保つために必要です。
3. 環境変数 $RBENV_VERSION の確認
もし rbenv local の設定が機能しない場合は、環境変数 $RBENV_VERSION が設定されていないか確認してください。この変数が設定されていると、.ruby-version のローカル設定よりも優先されます。
echo $RBENV_VERSION
設定を解除するには unset RBENV_VERSION を実行します。
この記事の作成者の紹介
山崎進
- Redmine、Jquery、JavaScript,Rails、Ruby、SQL、VBA、RPAの開発を行なっています。
- 自動化、業務の効率化に高い関心があります。
- 下記の媒体で情報を発信しています。Redmineのプラグインの開発などに対応が可能ですので、お気軽にご連絡ください。
* Qiita：https://qiita.com/ankosoft
* Twitter：https://twitter.com/yamasaki24
* Redmine Advent Calendarで記事投稿
* redmine.tokyoで講演多数
* Redmine Japan Vol.1 前夜祭、Redmine Japan Vol.3で講演
* https://ankosoft.co.jp/blog/
* https://technology.ankosoft.co.jp/
関連記事（2024年のRedmine Advent Calendarの記事です。）
* Redmine wikiマクロを作成する方法２（完了チケットの割合をグラフで表示）
* Redmine wikiマクロを作成する方法３（ステータスごとのチケットの割合をグラフで表示）
* Redmine wikiマクロを作成する方法４（ステータスごとのチケットの割合を一つのグラフで表示）
* Redmine wikiマクロを作成する方法５（特定のユーザーのチケット状態の確認）
* Redmine wikiマクロを作成する方法６（プロジェクトに所属する全てのユーザーのチケット状態の確認）
関連記事（2023年のRedmine Advent Calendarの記事です。）
* JqueryでRedmineのメニューにアイコンを入れる方法
* JqueryでRedmineのメニューを閉じたり開いたりする方法
* JqueryでRedmineの「活動ページ」をもっと便利に(タイトルを開閉したり、曜日を入れたり)
* JqueryでRedmineの「活動ページ」をもっと便利に②(フィルタリング機能と移動機能)
* JqueryでRedmineの「wikiページ」をもっと便利に(フィルタリング機能と移動機能)
* JqueryでRedmineの「チケットページ」をもっと便利に(年ごと、月ごと、四半期ごとの集計機能の開発)