# Configure a Ruby interpreter

> **TL;DR**
> Configure:  `Project Structure | Project Settings | Modules | Ruby Interpreters`
>
>
>
> Required plugin: [Ruby](ruby-plugin.html)

To work with your Ruby code in IntelliJ IDEA, you need to configure at least one Ruby interpreter. You can set up the interpreter for the currently opened project or when creating a [new project](get-started.html).

Configuration of the Ruby interpreter depends on the way you [installed it](https://www.jetbrains.com/help/ruby/set-up-a-ruby-development-environment.html#ruby):

* If you installed Ruby using a package manager (apt for Ubuntu, Homebrew for macOS, and so on) or Ruby installer (for example, RubyInstaller for Windows), you need to [add it manually](#add_local_ruby_interpreter).

* If you installed Ruby using a [version manager](https://www.jetbrains.com/help/ruby/ruby-version-managers.html), IntelliJ IDEA detects interpreters automatically. In this case, you can [select the desired version](#select_ruby_interpreter).

* If you [installed Ruby directly from IntelliJ IDEA](creating-and-running-your-first-language-project.html#create_empty_app), the installed interpreter is set as the default for the current project.

* If you are using Ruby installed in an isolated environment (Docker, Vagrant, WSL, and so on), IntelliJ IDEA allows you to configure it as a [remote interpreter](#add_remote_ruby_interpreter).

> **Tip:**
> For more information about supported Ruby versions, refer to  [this page](https://www.jetbrains.com/help/ruby/supported-ruby-versions.html).

## Add a local interpreter

Procedure: Add an interpreter

1. Open the Project Structure dialog `Ctrl+Alt+Shift+S` (Windows), `⌘ ;` (macOS), `⌘ ;` (IntelliJ IDEA Classic (macOS)), `⌘ ⇧ Comma` (macOS System Shortcuts), `Ctrl+Alt+Shift+S` (XWin), `Ctrl+Alt+Shift+S` (GNOME), `Ctrl+Alt+Shift+S` (KDE), `Ctrl+Alt+Shift+S` (Emacs), `Ctrl+Alt+Shift+S` (Sublime Text), `⌘ ;` (Sublime Text (macOS)), `Ctrl+Alt+Shift+S` (NetBeans), `Ctrl+Alt+Shift+S` (Visual Studio), `⌘ ;` (Visual Studio (macOS)), `Ctrl+Alt+Shift+S` (Eclipse), `⌘ ;` (Eclipse (macOS)) and select Modules on the left.

2. On the Ruby Interpreters page, click the ![add](https://resources.jetbrains.com/help/img/idea/2026.2/app.expui.general.add.svg) button and select Interpreter:

![New local interpreter](https://resources.jetbrains.com/help/img/idea/2026.2/ij_add_local_ruby_interpreter.png)

3. Provide a path to the Ruby executable, for example:

* For Ruby installed on macOS using Homebrew: `/opt/homebrew/opt/ruby/bin/ruby` for Apple Silicon `/usr/local/opt/ruby/bin/ruby` for Intel

* `/usr/bin/ruby` for Ruby installed on Linux using apt.

* `C:\Ruby26-x64\bin\ruby.exe` for Ruby installed on Windows using RubyInstaller.

IntelliJ IDEA will display the added interpreter along with automatically detected interpreters.

To remove the interpreter from the list, select it, and click the ![remove](https://resources.jetbrains.com/help/img/idea/2026.2/app.expui.general.remove.svg) button.

Procedure: Add an interpreter with custom environment

IntelliJ IDEA allows you to use your custom environment for running any Ruby command from within IntelliJ IDEA. To do this, you need to provide environment variable values or a path to a configuration script when adding a local interpreter.

1. Open the Project Structure dialog `Ctrl+Alt+Shift+S` (Windows), `⌘ ;` (macOS), `⌘ ;` (IntelliJ IDEA Classic (macOS)), `⌘ ⇧ Comma` (macOS System Shortcuts), `Ctrl+Alt+Shift+S` (XWin), `Ctrl+Alt+Shift+S` (GNOME), `Ctrl+Alt+Shift+S` (KDE), `Ctrl+Alt+Shift+S` (Emacs), `Ctrl+Alt+Shift+S` (Sublime Text), `⌘ ;` (Sublime Text (macOS)), `Ctrl+Alt+Shift+S` (NetBeans), `Ctrl+Alt+Shift+S` (Visual Studio), `⌘ ;` (Visual Studio (macOS)), `Ctrl+Alt+Shift+S` (Eclipse), `⌘ ;` (Eclipse (macOS)) and select Modules on the left.

2. On the Ruby page, click the ![add](https://resources.jetbrains.com/help/img/idea/2026.2/app.expui.general.add.svg) button and select Interpreter with Custom Environment:

3. In the invoked dialog, provide a path to the Ruby executable as described in [Add an interpreter](#add_local). Then, configure the Custom environment in one of the following ways:

* Specify the environment variable values directly. Example: `env API_KEY=123`

* If you use a shell script to load environment variables, you need to provide an absolute path to this script. Example: `/bin/bash /Users/jetbrains/sample_app/env.sh` > **Tip:** > Note that the `*.sh` file should have `"$@"` at the end to allow IntelliJ IDEA to pass some commands required for adding an interpreter.

* If you use [direnv](https://github.com/direnv/direnv) to load and unload environment variables, pass a path to the directory with the `.envrc` file to the `direnv exec` command. Example: `direnv exec /Users/jetbrains/sample_app`

* If you use [Shadowenv](https://github.com/Shopify/shadowenv) to customize your project environment, pass a path to the project directory to the `shadow exec` command. Example: `shadowenv exec --dir /Users/jetbrains/sample_app --`

Click OK to add an interpreter.

4. Select the added interpreter and click OK in the Settings dialog.

> **Note: Limitations**
> Interpreters with a custom environment do not support Ruby version managers. Do not combine a custom environment with interpreters managed by: rbenv. rvm, asdf, etc.
>
>
>
>
>
> Use either a version-manager-managed interpreter or an interpreter with a custom environment.
>
>
>
>
>
> If you need both, use a wrapper script that configures the environment and launches Ruby through the version manager.

## Select an auto-detected interpreter

Procedure: Select an interpreter on the Ruby page

To select an auto-detected Ruby interpreter maintained by the version manager, follow the steps below:

1. Invoke the Project Structure dialog `Ctrl+Alt+Shift+S` (Windows), `⌘ ;` (macOS), `⌘ ;` (IntelliJ IDEA Classic (macOS)), `⌘ ⇧ Comma` (macOS System Shortcuts), `Ctrl+Alt+Shift+S` (XWin), `Ctrl+Alt+Shift+S` (GNOME), `Ctrl+Alt+Shift+S` (KDE), `Ctrl+Alt+Shift+S` (Emacs), `Ctrl+Alt+Shift+S` (Sublime Text), `⌘ ;` (Sublime Text (macOS)), `Ctrl+Alt+Shift+S` (NetBeans), `Ctrl+Alt+Shift+S` (Visual Studio), `⌘ ;` (Visual Studio (macOS)), `Ctrl+Alt+Shift+S` (Eclipse), `⌘ ;` (Eclipse (macOS)) and select Modules on the left.

2. Choose the required Ruby interpreter. You can also choose the gemset for the RVM and rbenv version managers.

![Ruby Interpreters](https://resources.jetbrains.com/help/img/idea/2026.2/ij_local_sdk_gems_page.png)

3. For the selected Ruby interpreter/gemset, you can see the installed gems on the right.

Procedure: Switch an interpreter using Run Anything

If you use RVM or rbenv to manage local Ruby interpreters, you can quickly set the required interpreter using [Run Anything](running-anything.html):

1. Press `Ctrl` (Windows), `Ctrl` (macOS), `Ctrl` (IntelliJ IDEA Classic (macOS)), `Ctrl` (macOS System Shortcuts), `Ctrl` (XWin), `Ctrl` (GNOME), `Ctrl` (KDE), `Ctrl` (Emacs), `Ctrl` (Sublime Text), `Ctrl` (Sublime Text (macOS)), `Ctrl` (NetBeans), `Ctrl` (Visual Studio), `Ctrl` (Visual Studio (macOS)), `Ctrl` (Eclipse), `Ctrl` (Eclipse (macOS)) twice.

2. In the invoked popup, start typing `rvm use` or `rbenv shell`, select the required interpreter and press `Enter` (Windows), `⏎` (macOS), `⏎` (IntelliJ IDEA Classic (macOS)), `⏎` (macOS System Shortcuts), `Enter` (XWin), `Enter` (GNOME), `Enter` (KDE), `Enter` (Emacs), `Enter` (Sublime Text), `⏎` (Sublime Text (macOS)), `Enter` (NetBeans), `Enter` (Visual Studio), `⏎` (Visual Studio (macOS)), `Enter` (Eclipse), `⏎` (Eclipse (macOS)).

3. (Optional) If necessary, click the Rollback button in the popup that informs about the changed interpreter.

> **Tip:**
> Note that IntelliJ IDEA supports [with Ruby
> version managers](https://www.jetbrains.com/help/ruby/ruby-version-managers.html) based on the project files.

## Add a remote interpreter

> **Note:**
> We've seriously improved Remote Development, and now we recommend it as a better alternative to using remote interpreters. With Remote Development, your IDE runs directly on the remote machine, giving you a smoother, faster, and more reliable experience — with full support for all IDE features. Find more details in [this section](remote.html).

Various remote development tools, such as Docker, Vagrant, or Windows Subsystem for Linux (WSL), allow you to use an isolated environment for developing your applications. This can be useful in multiple cases, for example, if you want to:

* Develop in an isolated environment to avoid impacting your local machine configuration.

* Run, debug, and test your application on the same operating system you deploy.

* Develop Linux-deployed applications using the Windows Subsystem for Linux.

You can prepare the desired Ruby/Rails setup in a remote environment using Docker Compose, Vagrant box, or WSL. Then, you can add the [remote Ruby interpreter](#add_remote_ruby_interpreter) in IntelliJ IDEA and [run](running-applications.html), [debug](debugging-code.html), and [test](performing-tests.html) your application in an isolated environment right from the IDE.

Note that when you are using a remote interpreter, IntelliJ IDEA downloads gems from a remote machine to a local cache to be able to use code insight features. In this case, you may encounter a situation when new gems were installed on a remote machine outside the IDE. To update a set of gems stored in a local cache, click the Synchronize gems ![Synchronize gems](https://resources.jetbrains.com/help/img/idea/2026.2/app.actions.download.svg) button in the Ruby Interpreters page.

To configure a remote Ruby interpreter, follow these steps:

Procedure:

1. On the toolbar, click ![add](https://resources.jetbrains.com/help/img/idea/2026.2/app.expui.general.add.svg), and choose Remote Interpreter or Version Manager.

![New remote interpreter](https://resources.jetbrains.com/help/img/idea/2026.2/ij_add_remote_ruby_interpreter.png)

2. In the Configure Remote Ruby Interpreter dialog, perform the steps provided on the respective tab below.

SSH:

> **Note: Prerequisite**
> Before performing the steps below, make sure you set up SSH and added an SSH configuration. Find more details in [this
> topic](running-ssh-terminal.html).

Procedure:

1. Specify the following options:

![Configure remote ruby interpreter: SSH](https://resources.jetbrains.com/help/img/idea/2026.2/rm_remote_attach_ssh_credentials.png)

* SSH configuration: Expand the list of existing SSH configurations or click the ellipsis button and create a new one.

* Ruby or version manager path: Specify the path to the Ruby interpreter or the version manager executable.

2. Click OK. If you specified a path to the version manager executable on the previous step, IntelliJ IDEA suggests selecting the Ruby interpreter used to run a remote application.

3. On the Ruby page, select the added interpreter and click OK.

Docker:

> **Note: Prerequisite**
> Before performing the steps below, make sure you have built a Docker image. Find more details in [this topic](docker-images.html#build-image)

Procedure:

1. In the invoked dialog, select Docker and specify the following options:

![Configure remote Ruby interpreter: Docker](https://resources.jetbrains.com/help/img/idea/2026.2/docker_tutorial_configure_remote.png)

* Server: Specify a Docker server used to run a container.

* Image name: Select the [previously built image](docker-images.html#build-image).

* Ruby or version manager path: Leave the default `ruby` value to detect a path to the Ruby interpreter automatically.

2. Click OK. If you specified a path to the version manager executable on the previous step, IntelliJ IDEA suggests selecting the Ruby interpreter used to run a remote application.

The added interpreter is now available on the Ruby page.

3. Select the added interpreter and click OK in the Ruby Interpreters dialog.

Wait until IntelliJ IDEA finishes the project analysis process and creates helper Docker images and containers.

![Docker tool window](https://resources.jetbrains.com/help/img/idea/2026.2/docker_tutorial_dockerfile_tool_window_add_interpreter.png)

Docker Compose:

> **Note: Prerequisite**
> Before performing the steps below, make sure you built a Docker Compose application. Find more details in [this
> topic](docker-compose.html#create-docker-compose-run-configuration).

Procedure:

1. In the invoked dialog, select Docker Compose and specify the following options:

![Configure remote Ruby interpreter: Docker Compose](https://resources.jetbrains.com/help/img/idea/2026.2/docker_tutorial_configure_remote_compose.png)

* Server: this option specifies a Docker server used to run a container.

* Configuration files: leave the `docker-compose.yml` file.

* Service: select the web service.

* Environment variables: Normally, does not need to be changed. If you do want to customize them, click the Edit environment variables icon to open the Environment Variables dialog. You can either add a new variable (click the + icon) or edit system environment variables, which are included by default. ![Edit environment variables](https://resources.jetbrains.com/help/img/idea/2026.2/rm_docker_compose_edit_variables.png)

* Node.js runtime path: Leave the default `ruby` value to detect a path to the Ruby interpreter automatically. You can also manually specify the path to the interpreter or the version manager executable.

2. Click OK. If you specified a path to the version manager executable on the previous step, IntelliJ IDEA suggests selecting the Ruby interpreter used to run a remote application.

The added interpreter is now available on the Ruby page.

![Ruby Interpreters: Docker Compose](https://resources.jetbrains.com/help/img/idea/2026.2/docker_tutorial_ruby_sdk_page_compose.png)

3. Select the added interpreter and click OK in the Ruby Interpreters dialog.

Wait until IntelliJ IDEA finishes the project analysis process and creates helper Docker images and containers.

![Docker tool window: Helpers](https://resources.jetbrains.com/help/img/idea/2026.2/docker_tutorial_compose_tool_window_helpers.png)

> **Note:**
> Ruby helpers are additional containers and Docker images that IntelliJ IDEA creates for testing and debugging purposes. They contain gems and `.rb` scripts that IntelliJ IDEA uses to prepare the test environment, convert the output of test libraries (for example, Minitest, RSpec, Cucumber), launch tests, and so on.

Vagrant:

> **Note: Prerequisite**
> Before performing the steps below, make sure you initialized a Vagrant environment, created and booted the virtual machine, and SSHed into it. Find more details in

Procedure:

1. In the invoked dialog, select Vagrant.

![rm_remote_sdk_vagrant.png](https://resources.jetbrains.com/help/img/idea/2026.2/rm_remote_sdk_vagrant.png)

If a project root folder contains a `Vagrantfile` pointing to a running virtual machine, IntelliJ IDEA detects the Vagrant Instance Folder automatically and displays the Vagrant Host URL used to access the virtual machine. If necessary, you can change the Vagrant Instance Folder to use another virtual machine.

In Ruby or version manager path, specify the path to the Ruby interpreter or the version managerexecutable. Click OK.

2. (Optional) If you specified a path to the version manager executable on the previous step, IntelliJ IDEA suggests selecting the Ruby interpreter used to run a remote application.

3. Select the added interpreter on the Ruby Interpreters page and click OK.

Wait until IntelliJ IDEA downloads gems from the remote machine to local caches. This is required for indexing.

WSL:

IntelliJ IDEA allows you to use the remote Ruby interpreter installed on Windows Subsystem for Linux ([WSL](https://docs.microsoft.com/en-us/windows/wsl/) and WSL 2) for your local projects.

> **Note: Prerequisite**
> Before performing the steps below, make sure you configured WSL. Find more details in [this
> topic](how-to-use-wsl-development-environment-in-product.html#wsl-general).

Procedure:

1. In the invoked dialog, select WSL:

Choose the desired Linux distribution.

In Ruby or version manager path, specify the path to the Ruby interpreter or the version managerexecutable. Click OK.

2. (Optional) If you specified a path to the version manager executable in the previous dialog, IntelliJ IDEA suggests selecting the Ruby interpreter used to run a remote application.

3. Select the added interpreter in the Ruby Interpreters dialog and click OK.

Procedure: (Optional) Edit mappings between local and remote project files

1. Specify mappings between files of a local and remote project. To do this, click the ![Edit Path Mappings](https://resources.jetbrains.com/help/img/idea/2026.2/app.vcs.folders.svg) button.

![Edit path mappings](https://resources.jetbrains.com/help/img/idea/2026.2/ij_edit_path_mappings.png)

2. In the Edit Project Path Mappings dialog, specify the local and remote project root paths.

![Edit Project Path Mappings](https://resources.jetbrains.com/help/img/idea/2026.2/rm_remote_attach_path_mappings.png)

Note that IntelliJ IDEA detects Vagrant [synced folders](https://www.vagrantup.com/docs/synced-folders/), WSL mappings, and so on. These mappings are listed in this dialog and cannot be changed.

> **Tip:**
> By default, IntelliJ IDEA installed on Linux or macOS downloads remote gems using the rsync utility. This speeds up the downloading process. You can change the default behavior and disable the use of rsync by utilizing the IntelliJ IDEA registry. To invoke the Registry dialog, press   `Ctrl+Shift+A` (Windows), `⌘ ⇧ A` (macOS), `⌘ ⇧ A` (IntelliJ IDEA Classic (macOS)), `⌘ ⇧ P` (macOS System Shortcuts), `Ctrl+Shift+A` (XWin), `Ctrl+Shift+A` (GNOME), `Ctrl+Shift+A` (KDE), `Escape, X` (Emacs), `Ctrl+Shift+P` (Sublime Text), `⌘ ⇧ P` (Sublime Text (macOS)), `Ctrl+I` (NetBeans), `Ctrl+Shift+A` (Visual Studio), `⌘ ⇧ A` (Visual Studio (macOS)), `Ctrl+Shift+A` (Eclipse), `⌘ 3` (Eclipse (macOS)) or choose `Help | Find Action` from the main menu. In the popup that opens, start typing `Registry`, select the corresponding item and press `Enter` (Windows), `⏎` (macOS), `⏎` (IntelliJ IDEA Classic (macOS)), `⏎` (macOS System Shortcuts), `Enter` (XWin), `Enter` (GNOME), `Enter` (KDE), `Enter` (Emacs), `Enter` (Sublime Text), `⏎` (Sublime Text (macOS)), `Enter` (NetBeans), `Enter` (Visual Studio), `⏎` (Visual Studio (macOS)), `Enter` (Eclipse), `⏎` (Eclipse (macOS)).   Then, use the following options to enable or disable rsync:
>
>
>
> * Linux and macOS: `ide.remote.interpreters.use.rsync`
>
> * Windows: `ide.remote.interpreters.rsync.enabled.on.windows`

## Edit an interpreter

You can customize the names of Ruby interpreters to distinguish them quickly and avoid duplication.

Procedure:

1. Open the Project Structure dialog `Ctrl+Alt+Shift+S` (Windows), `⌘ ;` (macOS), `⌘ ;` (IntelliJ IDEA Classic (macOS)), `⌘ ⇧ Comma` (macOS System Shortcuts), `Ctrl+Alt+Shift+S` (XWin), `Ctrl+Alt+Shift+S` (GNOME), `Ctrl+Alt+Shift+S` (KDE), `Ctrl+Alt+Shift+S` (Emacs), `Ctrl+Alt+Shift+S` (Sublime Text), `⌘ ;` (Sublime Text (macOS)), `Ctrl+Alt+Shift+S` (NetBeans), `Ctrl+Alt+Shift+S` (Visual Studio), `⌘ ;` (Visual Studio (macOS)), `Ctrl+Alt+Shift+S` (Eclipse), `⌘ ;` (Eclipse (macOS)) and select Modules on the left.

2. Right-click the required Ruby interpreter and select Edit name.

![Rename parameter in code and Ruby interpreter](https://resources.jetbrains.com/help/img/idea/2026.2/ij_edit_interpreter.png)

Alternatively, you can select the required Ruby interpreter and use the ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.expui.general.edit.svg) icon or press `Enter` (Windows), `⏎` (macOS), `⏎` (IntelliJ IDEA Classic (macOS)), `⏎` (macOS System Shortcuts), `Enter` (XWin), `Enter` (GNOME), `Enter` (KDE), `Enter` (Emacs), `Enter` (Sublime Text), `⏎` (Sublime Text (macOS)), `Enter` (NetBeans), `Enter` (Visual Studio), `⏎` (Visual Studio (macOS)), `Enter` (Eclipse), `⏎` (Eclipse (macOS)).

3. In the Edit interpreter dialog, provide a new name for the interpreter and click OK.

![Enter a new name for the Ruby interpreter](https://resources.jetbrains.com/help/img/idea/2026.2/rm_edit_interpreter_dialog.png)

## Create RVM gemsets

To create an RVM gemset, open the Product Structure dialog (`Ctrl+Alt+Shift+S` (Windows), `⌘ ;` (macOS), `⌘ ;` (IntelliJ IDEA Classic (macOS)), `⌘ ⇧ Comma` (macOS System Shortcuts), `Ctrl+Alt+Shift+S` (XWin), `Ctrl+Alt+Shift+S` (GNOME), `Ctrl+Alt+Shift+S` (KDE), `Ctrl+Alt+Shift+S` (Emacs), `Ctrl+Alt+Shift+S` (Sublime Text), `⌘ ;` (Sublime Text (macOS)), `Ctrl+Alt+Shift+S` (NetBeans), `Ctrl+Alt+Shift+S` (Visual Studio), `⌘ ;` (Visual Studio (macOS)), `Ctrl+Alt+Shift+S` (Eclipse), `⌘ ;` (Eclipse (macOS))), go to Modules | Ruby Interpreters, and perform the following steps:

Procedure:

1. Right-click the required interpreter and select New RVM gemset

![Ruby Interpreters page](https://resources.jetbrains.com/help/img/idea/2026.2/ij_gemsets_rvm_sdk_page_example_initial.png)

2. In the dialog that opens, select the Ruby interpreter, for which the gemset will be created. Then, specify the gemset name and click OK:

![create new rvm gemset dialog](https://resources.jetbrains.com/help/img/idea/2026.2/rm_gemsets_rvm_sdk_page_new_gemset_dialog.png)

3. The Ruby Interpreters  page will show the gemset as a child of the selected interpreter:

![Ruby Interpreters page](https://resources.jetbrains.com/help/img/idea/2026.2/ij_gemsets_rvm_sdk_page_created_asterisk.png)

Note that the asterisk is appended to the gemset name. This means that gemset is not created yet. To create it, click Apply or OK in the Product Structure dialog.

## Troubleshooting

Procedure: Configure a local interpreter for a Ruby project

If you encounter issues when configuring a local interpreter for a newly-cloned Ruby project (for example, the Ruby Interpreters page is not displayed), try opening this project from existing sources.

1. In the main menu, go to `File | New | Project from existing sources`.

2. Provide the path to your project.

3. In the Import Project dialog, select the Create project from existing sources option and click Next.

4. Specify the project name and path to the directory in which you want to create the project. Click Next.

5. Select the directories that you want to add to the project roots and click Next.

6. Select the frameworks that you want to use in your project. Click Finish.

Once IntelliJ IDEA opens your project, follow the steps described in [Add an interpreter](#add_local) to configure a local interpreter.

## Remove an interpreter

> **Note:**
> You can only remove interpreters that you manually added to the Ruby Interpreters list.
>
> Automatically detected interpreters
>
> The IDE UI does not allow you to remove the following:
>
>
>
> * Automatically detected interpreters (system Ruby, rbenv, rvm, asdf, etc.)
>
> * Interpreters created using a custom environment together with a Ruby version manager

Procedure:

1. Go to  `Project Structure | Project Settings | Modules | Ruby Interpreters`

2. From the list of interpreters, select the manually added interpreter you want to remove.

3. Click the ![remove](https://resources.jetbrains.com/help/img/idea/2026.2/app.expui.general.remove.svg) button from the toolbar on top of the Ruby page.

![Removing an added interpreter](https://resources.jetbrains.com/help/img/idea/2026.2/ij_remove_interpreter.png)

4. Click OK in the invoked dialog.

## See also

### Concepts

[Projects](creating-and-managing-projects.html)