VSCodeでRuby LSPを設定する方法について

2026年10月26日

VSCodeでRubyを効率よく開発したい場合は、Shopifyが提供している「Ruby LSP」拡張機能を利用する方法がおすすめです。

Ruby LSPを導入すると、コード補完や定義への移動、Hoverによる情報表示、シンボル検索、コードフォーマット、RuboCopによる診断、テスト実行、デバッグなど、Ruby開発に役立つさまざまな機能をVSCode上で利用できます。

Ruby LSPはRubyやRailsの開発環境と連携して動作するため、単にVSCodeへ拡張機能をインストールするだけでなく、RubyやBundlerの環境を正しく整えておくことが重要です。

ここでは、VSCodeでRuby LSPを設定する方法について詳しく解説します。

Ruby LSPとは

Ruby LSPとは、Ruby向けのLanguage Server Protocolを実装した言語サーバーです。

Language Server Protocolは、プログラミング言語の解析機能とVSCodeなどのエディターを連携させるための仕組みです。

Ruby LSPを使用することで、Rubyコードを解析しながら、さまざまな編集支援機能を利用できるようになります。

Ruby LSPで利用できる主な機能

Ruby LSPでは、主に次のような機能を利用できます。

コード補完
定義への移動
Hoverによる情報表示
ドキュメントシンボル検索
ワークスペースシンボル検索
セマンティックハイライト
コードフォーマット
コード診断
RuboCopとの連携
テストの実行
テストのデバッグ
Rubyプログラムのデバッグ
Railsとの連携

VSCode向けのRuby LSP拡張機能はShopifyによって開発されています。

VSCodeでRuby LSPを設定する基本的な流れ

VSCodeでRuby LSPを利用するときは、基本的に次の順番で環境を整えます。

Rubyをインストールする
Rubyのバージョン管理環境を整える
Bundlerを利用できる状態にする
VSCodeへRuby LSP拡張機能をインストールする
RubyプロジェクトをVSCodeで開く
Ruby LSPが正常に起動しているか確認する
必要に応じてRuboCopやフォーマッターを設定する

Ruby LSPは多くの処理を自動化しているため、一般的なRubyプロジェクトであれば設定項目を大量に追加する必要はありません。

まずは標準設定で起動し、問題が発生した場合だけRubyバージョン管理ツールやフォーマッターなどを明示的に指定するとよいでしょう。

Rubyをインストールする

Rubyのバージョンを確認する

Ruby LSPを使用するには、Rubyが利用できる環境が必要です。

VSCodeのターミナルなどから次のコマンドを実行します。

ruby -v

Rubyが正しくインストールされていれば、バージョン情報が表示されます。

例えば、次のように表示されます。

ruby 3.x.x

続いてBundlerも確認しておきます。

bundle -v

Bundlerのバージョンが表示されれば、基本的なRuby開発環境は準備できています。

Rubyのバージョン管理ツールを利用する

Ruby開発では、OSに最初からインストールされているRubyを直接利用するのではなく、Rubyのバージョン管理ツールを使用するのが一般的です。

代表的なツールとして、次のようなものがあります。

rbenv
mise
asdf
chruby
RVM

Ruby LSPは複数のRubyバージョン管理ツールに対応しており、通常は使用している環境を自動的に判別します。

そのため、最初からRuby LSP側でバージョン管理ツールを明示的に設定する必要はありません。

VSCodeへRuby LSPをインストールする

拡張機能画面を開く

VSCodeを起動し、左側にある「Extensions」を開きます。

WindowsやLinuxでは、次のショートカットでも開けます。

Ctrl + Shift + X

macOSでは次のショートカットです。

Command + Shift + X

Ruby LSPを検索する

検索欄に次のように入力します。

Ruby LSP

Shopifyが提供している「Ruby LSP」を選択し、「Install」をクリックします。

拡張機能IDは次のとおりです。

Shopify.ruby-lsp

名前が似ている別のRuby拡張機能も存在するため、PublisherがShopifyになっていることを確認するとよいでしょう。

RubyプロジェクトをVSCodeで開く

Ruby LSPを利用するときは、Rubyファイルを1つだけ開くのではなく、プロジェクトのルートディレクトリをVSCodeで開くことが重要です。

例えばRailsプロジェクトであれば、次のような構成になっています。

myapp/
├── Gemfile
├── Gemfile.lock
├── app/
├── config/
├── db/
└── ...

この場合はmyappディレクトリをVSCodeで開きます。

ターミナルから開く場合は、次のように実行します。

cd myapp
code .

Ruby LSPはGemfileやGemfile.lockなどを参照してプロジェクトの依存関係を解析します。

そのため、適切なプロジェクトルートを開くことが重要です。

Bundlerの依存関係を整える

Ruby LSPを正常に利用するには、プロジェクトの依存関係がBundlerによって正しく解決できる状態になっている必要があります。

既存プロジェクトであれば、次のコマンドを実行しておくとよいでしょう。

bundle install

Ruby LSP自身も必要に応じてBundlerを利用しますが、プロジェクト側のbundle installがエラーになる状態では、Ruby LSPも正常に動作しない可能性があります。

そのため、Ruby LSPで問題が発生した場合は、まずプロジェクト側でbundle installが正常に完了するか確認することが重要です。

Ruby LSPのcomposed bundleとは

VSCode版Ruby LSPでは、プロジェクトのGemfileへ必ずruby-lspを追加する必要はありません。

Ruby LSP拡張機能は、プロジェクト内に次のようなディレクトリを作成する場合があります。

.ruby-lsp/

このディレクトリ内で、Ruby LSPを動作させるための専用bundleが構築されます。

Gemfileへruby-lspを追加する必要は基本的にない

一般的なVSCodeでの利用では、プロジェクトのGemfileへ次のような記述を追加する必要はありません。

gem "ruby-lsp"

Ruby LSP拡張機能が必要な依存関係を.ruby-lsp側で管理するためです。

そのため、特別な理由がなければRuby LSPの依存関係は拡張機能側に任せるのが分かりやすいでしょう。

Ruby LSPが起動しているか確認する

ステータスを確認する

Rubyファイルを開くと、VSCode内でRuby LSPが起動します。

Ruby LSPの状態が正常であれば、言語サーバーがRunning状態になります。

Ruby LSPが起動しない場合は、VSCodeのRuby言語ステータスや出力パネルを確認すると原因を調べやすくなります。

定義への移動を確認する

Ruby LSPが正常に動作しているか確認する方法として、「定義へ移動」を試す方法があります。

例えば次のようなコードを用意します。

class User
  def hello
    "Hello"
  end
end

user = User.new
user.hello

Userやhelloにカーソルを合わせて「Go to Definition」を実行します。

定義位置へ移動できれば、Ruby LSPが正常に機能している可能性が高いでしょう。

Hoverやコード補完も確認する

クラス名やメソッド名へマウスカーソルを合わせると、Ruby LSPが解析した情報が表示される場合があります。

また、コード入力時に補完候補が表示されるかどうかも確認しておくとよいでしょう。

Rubyのバージョン管理ツールを設定する

Ruby LSPは通常、使用しているRuby環境を自動検出します。

標準では、次のような設定に相当します。

{
  "rubyLsp.rubyVersionManager": {
    "identifier": "auto"
  }
}

通常はこの設定を明示的に記述する必要はありません。

rbenvを明示的に指定する

自動検出が正常に機能しない場合は、使用しているRubyバージョン管理ツールを明示できます。

rbenvの場合は次のように設定します。

{
  "rubyLsp.rubyVersionManager": {
    "identifier": "rbenv"
  }
}

miseを明示的に指定する

miseを使用している場合は次のように設定できます。

{
  "rubyLsp.rubyVersionManager": {
    "identifier": "mise"
  }
}

ただし、通常はautoのまま利用し、問題が発生した場合だけ変更するのがおすすめです。

Ruby LSPとシェル環境の関係

Ruby LSPでトラブルが起きやすいポイントの一つが、RubyのPATHやシェル環境です。

VSCodeのターミナルでは次のコマンドが正常に動作していても、Ruby LSP側では別のRubyを認識してしまう場合があります。

ruby -v

これは、VSCode本体とターミナルで読み込まれる環境変数が異なることがあるためです。

シェル設定を確認する

rbenvやmiseなどを利用している場合は、シェルの設定ファイルを確認します。

代表的な設定ファイルには次のようなものがあります。

~/.zshrc

~/.bashrc

Rubyバージョン管理ツールの初期化設定が正しく記述されているか確認しましょう。

また、Ruby環境を変更した直後はVSCodeを完全に終了して再起動することで解決する場合もあります。

Ruby LSPで自動フォーマットを設定する

Ruby LSPを導入したら、保存時の自動フォーマットを設定しておくと便利です。

例えばsettings.jsonに次のように設定できます。

{
  "[ruby]": {
    "editor.defaultFormatter": "Shopify.ruby-lsp",
    "editor.formatOnSave": true,
    "editor.formatOnType": true,
    "editor.tabSize": 2,
    "editor.insertSpaces": true,
    "editor.semanticHighlighting.enabled": true
  },
  "rubyLsp.formatter": "auto"
}

editor.defaultFormatter

次の設定は、RubyファイルのフォーマッターとしてRuby LSPを使用する指定です。

"editor.defaultFormatter": "Shopify.ruby-lsp"

editor.formatOnSave

次の設定を有効にすると、Rubyファイルを保存したタイミングで自動フォーマットが実行されます。

"editor.formatOnSave": true

editor.formatOnType

次の設定では、入力時のフォーマット機能を有効にできます。

"editor.formatOnType": true

rubyLsp.formatter

Ruby LSPで使用するフォーマッターは次の設定で指定します。

"rubyLsp.formatter": "auto"

autoを使用すると、Ruby LSPがプロジェクトの依存関係を確認し、利用可能なフォーマッターを自動的に選択します。

Ruby LSPとRuboCopを連携する

Ruby開発では、Ruby LSPとRuboCopを組み合わせると、コードフォーマットや静的解析を利用しやすくなります。

RuboCopをGemfileへ追加する

例えば次のようにGemfileへ追加します。

group :development, :test do
  gem "rubocop", require: false
end

続いて次のコマンドを実行します。

bundle install

Ruby LSPがRuboCopを認識すれば、診断やフォーマットなどに利用できます。

RuboCopを明示的にフォーマッターとして指定する

RuboCopを明示的に使用する場合は、次のように設定できます。

{
  "rubyLsp.formatter": "rubocop"
}

一方、Ruby LSPに自動判別させる場合は次の設定で構いません。

{
  "rubyLsp.formatter": "auto"
}

通常はautoのまま利用するほうが管理しやすいでしょう。

Ruby LSPをRailsで利用する

Ruby LSPはRailsプロジェクトでも利用できます。

現在のRuby LSPでは、Railsプロジェクトを検出するとRails連携用のruby-lsp-railsアドオンを自動的に導入する仕組みがあります。

ruby-lsp-railsを手動追加する必要は基本的にない

一般的なRailsプロジェクトでは、Gemfileへ次の記述を追加する必要はありません。

gem "ruby-lsp-rails"

Ruby LSPがRailsプロジェクトを認識すると、.ruby-lsp側のcomposed bundleに必要なRails連携機能が組み込まれます。

そのため、通常はRuby LSP拡張機能をインストールしてRailsプロジェクトを開くだけで構いません。

Rails固有の機能も利用できる

Ruby LSPとRailsアドオンを組み合わせることで、Railsプロジェクト向けの機能も利用できます。

例えば、Rails関連のコード解析やテスト実行、Railsジェネレーター関連のコマンドなどを利用できます。

Ruby LSPでデバッグする

Ruby LSPのVSCode拡張機能には、Rubyプログラムのデバッグ機能も用意されています。

launch.jsonを作成する

VSCodeのコマンドパレットから次のコマンドを選択します。

Debug: Add Configuration...

すると.vscode/launch.jsonを作成できます。

例えば、現在開いているRubyファイルをデバッグする場合は次のような設定を利用できます。

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "ruby_lsp",
      "request": "launch",
      "name": "Debug program",
      "program": "ruby ${file}"
    }
  ]
}

テストファイルをデバッグする

Minitestなどのテストファイルをデバッグする場合は、次のような設定例があります。

{
  "type": "ruby_lsp",
  "request": "launch",
  "name": "Debug test file",
  "program": "ruby -Itest ${relativeFile}"
}

Ruby LSPのデバッグ設定では、現行仕様に合わせてprogramを使用するのがポイントです。

Ruby LSPを再起動する

GemfileやRubyバージョンを変更したあと、Ruby LSPの状態がおかしくなる場合があります。

その場合はRuby LSPを再起動してみましょう。

コマンドパレットから再起動する

WindowsやLinuxでは次のショートカットでコマンドパレットを開きます。

Ctrl + Shift + P

macOSでは次のショートカットです。

Command + Shift + P

検索欄へ次のように入力します。

Ruby LSP

Ruby LSPには、次のようなコマンドがあります。

Ruby LSP: Start
Ruby LSP: Restart
Ruby LSP: Stop
Ruby LSP: Update language server gem

トラブルが発生した場合は、まず次のコマンドを試すとよいでしょう。

Ruby LSP: Restart

Ruby LSPの状態を診断する

Ruby LSPが正常に起動しない場合は、診断機能を利用できます。

コマンドパレットから次のコマンドを実行します。

Ruby LSP: Diagnose language server state

Ruby環境やBundler、Ruby LSPの状態を確認する際に便利です。

問題が発生した場合は、単純に拡張機能を再インストールする前に診断結果を確認すると原因を特定しやすくなります。

Ruby LSPを更新する

Ruby LSPのVSCode拡張機能と、実際に言語サーバーとして動作するRuby LSPのgemは別のコンポーネントです。

Ruby LSPのサーバー側を更新したい場合は、コマンドパレットから次のコマンドを利用できます。

Ruby LSP: Update language server gem

通常はRuby LSP拡張機能側の自動管理に任せても問題ありません。

Ruby LSP専用のGemfileを使用する方法

通常は必要ありませんが、古いRubyを使用しているプロジェクトなどでは、Ruby LSP専用のGemfileを用意する方法があります。

例えば次のような構成にします。

tools/
└── ruby-lsp/
    ├── .ruby-version
    ├── Gemfile
    └── Gemfile.lock

Gemfileは例えば次のように記述します。

source "https://rubygems.org"

gem "ruby-lsp"
gem "rubocop"

依存関係をインストールします。

bundle install

そのうえでRuby LSPへGemfileの場所を指定します。

{
  "rubyLsp.bundleGemfile": "/path/to/tools/ruby-lsp/Gemfile"
}

ただし、この方法は一般的なRubyプロジェクト向けの基本設定ではありません。

Ruby LSPがサポートしていない古いRubyを利用する場合など、特殊なケースで検討する方法です。

Ruby LSPが動かない場合の対処法

Ruby LSPが起動しない場合は、順番に原因を切り分けていくことが重要です。

Rubyのバージョンを確認する

まず次のコマンドを実行します。

ruby -v

macOSやLinuxでは、Rubyの実行ファイルの場所も確認できます。

which ruby

意図したRubyが使用されているか確認しましょう。

Bundlerを確認する

次のコマンドを実行します。

bundle -v

続いてプロジェクトルートで次のコマンドを実行します。

bundle install

ここでエラーになる場合は、Ruby LSPより先にRubyやBundlerの環境を修正する必要があります。

Rubyバージョン管理ツールを確認する

rbenvを利用している場合は次のように確認できます。

rbenv versions

miseなら次のコマンドが利用できます。

mise current

ターミナルでは正常なのにRuby LSPだけ起動しない場合は、Ruby LSPが使用しているRubyとターミナル側のRubyが一致しているか確認しましょう。

Ruby LSPを再起動する

コマンドパレットから次のコマンドを実行します。

Ruby LSP: Restart

GemfileやRubyバージョンを変更した直後には特に有効です。

VSCodeを再起動する

Rubyバージョン管理ツールやPATHの設定を変更した場合は、VSCode自体を完全に終了して再起動すると改善する場合があります。

settings.jsonの設定が反映されない場合

Ruby LSPでは、Rubyの実行環境に影響する一部設定にセキュリティ上の制限があります。

そのため、プロジェクト内の.vscode/settings.jsonへ設定を書いても、内容によっては期待どおり反映されない場合があります。

対象となる代表的な設定には、次のようなものがあります。

rubyLsp.rubyExecutablePath
rubyLsp.customRubyCommand
rubyLsp.rubyVersionManager
rubyLsp.bundleGemfile

Ruby実行環境に関係する設定を変更する場合は、VSCodeのUser SettingsやMachine Settings側も確認するとよいでしょう。

Dev ContainersでRuby LSPを使用する場合

DockerやVSCode Dev Containersを利用している場合は、Ruby LSPを実行する場所にも注意が必要です。

例えば次のような構成の場合です。

Windows・macOS・Linux
        ↓
      VSCode
        ↓
   Dev Container
        ↓
      Ruby
        ↓
     Bundler
        ↓
      Rails

RubyやgemがDev Container内に存在する場合、Ruby LSPも基本的にはコンテナ側で動作させます。

Ruby LSP拡張機能をDev Container側へインストールし、RubyやBundlerへアクセスできる環境で動作させることが重要です。

Ruby LSPを設定するときのポイント

最初から設定を増やしすぎない

Ruby LSPは多くの設定を自動判別できます。

そのため、最初から大量の設定を追加する必要はありません。

まずはRuby LSP拡張機能をインストールしてプロジェクトを開き、正常に動作するか確認しましょう。

RubyとBundlerの環境を先に整える

Ruby LSPのトラブルは、Ruby LSPそのものではなく、RubyやBundlerの設定が原因になっている場合があります。

まず次のコマンドが正常に動作する状態を作ることが重要です。

ruby -v
bundle -v
bundle install

Ruby LSPとプロジェクトで同じRubyを使う

ターミナルとRuby LSPで異なるRubyが使用されると、gemが見つからないなどの問題が発生する場合があります。

rbenvやmiseなどを利用している場合は、Ruby LSPが正しいRubyを認識しているか確認しましょう。

まとめ

VSCodeでRubyを開発する場合は、Shopifyが提供している「Ruby LSP」拡張機能を導入すると、コード補完、定義への移動、コード診断、フォーマット、テスト実行、デバッグなどの機能を利用できます。

現在のRuby LSPでは、プロジェクト内に.ruby-lspディレクトリを作成してcomposed bundleを管理する仕組みが採用されています。

そのため、一般的なVSCodeでの利用であれば、プロジェクトのGemfileへruby-lspを手動で追加する必要はありません。

Railsプロジェクトについても、Railsを検出するとruby-lsp-railsが自動的に導入されるため、通常はGemfileへの手動追加は不要です。

Ruby LSPを設定するときに特に重要なのは、RubyやBundlerが正常に動作していることです。

まずは、

ruby -v
bundle -v
bundle install

が正常に実行できる状態を整え、そのうえでShopifyのRuby LSP拡張機能をインストールするとよいでしょう。

フォーマットについては、

"rubyLsp.formatter": "auto"

を利用し、保存時フォーマットを有効にする場合は、

"editor.formatOnSave": true

を組み合わせると便利です。

Ruby LSPが正常に起動しない場合は、Rubyのバージョン、Bundler、Rubyバージョン管理ツール、シェル設定を確認し、「Ruby LSP: Restart」や「Ruby LSP: Diagnose language server state」を利用して原因を切り分けましょう。

以上、VSCodeでRuby LSPを設定する方法についてでした。

最後までお読みいただき、ありがとうございました。

よかったらシェアしてね！

URLをコピーしました！

URLをコピーしました！

VSCodeでRuby LSPを設定する方法について

採用はこちら

Ruby LSPとは

Ruby LSPで利用できる主な機能

VSCodeでRuby LSPを設定する基本的な流れ

Rubyをインストールする

Rubyのバージョンを確認する

Rubyのバージョン管理ツールを利用する

VSCodeへRuby LSPをインストールする

拡張機能画面を開く

Ruby LSPを検索する

RubyプロジェクトをVSCodeで開く

Bundlerの依存関係を整える

Ruby LSPのcomposed bundleとは

Gemfileへruby-lspを追加する必要は基本的にない

Ruby LSPが起動しているか確認する

ステータスを確認する

定義への移動を確認する

Hoverやコード補完も確認する

Rubyのバージョン管理ツールを設定する

rbenvを明示的に指定する

miseを明示的に指定する

Ruby LSPとシェル環境の関係

シェル設定を確認する

Ruby LSPで自動フォーマットを設定する

editor.defaultFormatter

editor.formatOnSave

editor.formatOnType

rubyLsp.formatter

Ruby LSPとRuboCopを連携する

RuboCopをGemfileへ追加する

RuboCopを明示的にフォーマッターとして指定する

Ruby LSPをRailsで利用する

ruby-lsp-railsを手動追加する必要は基本的にない

Rails固有の機能も利用できる

Ruby LSPでデバッグする

launch.jsonを作成する

テストファイルをデバッグする

Ruby LSPを再起動する

コマンドパレットから再起動する

Ruby LSPの状態を診断する

Ruby LSPを更新する

Ruby LSP専用のGemfileを使用する方法

Ruby LSPが動かない場合の対処法

Rubyのバージョンを確認する

Bundlerを確認する

Rubyバージョン管理ツールを確認する

Ruby LSPを再起動する

VSCodeを再起動する

settings.jsonの設定が反映されない場合

Dev ContainersでRuby LSPを使用する場合

おすすめのsettings.json

Ruby LSPを設定するときのポイント

最初から設定を増やしすぎない

RubyとBundlerの環境を先に整える

Ruby LSPとプロジェクトで同じRubyを使う

まとめ

関連記事