Configure a Ruby interpreter

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.

Configuration of the Ruby interpreter depends on the way you installed it:

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.
If you installed Ruby using a version manager, IntelliJ IDEA should detect interpreters automatically. In this case, you can select the desired version.
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 a local interpreter

Add an interpreter

Open the Project Structure dialog Ctrl+Alt+Shift+S and select Modules on the left.
In the Ruby SDK and Gems page, click the button and select Interpreter:
Provide a path to the Ruby executable, for example:
- /usr/local/bin/ruby for Ruby installed on macOS using Homebrew.
- /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 button.

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.

Open the Project Structure dialog Ctrl+Alt+Shift+S and select Modules on the left.
In the Ruby SDK and Gems page, click the button and select Interpreter with Custom Environment:
In the invoked dialog, provide a path to the Ruby executable as described in Add an interpreter. 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
  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 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 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.
Select the added interpreter and click OK in the Settings dialog.

Select an auto-detected interpreter

Select an interpreter on the Ruby SDK and Gems page

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

Invoke the Project Structure dialog Ctrl+Alt+Shift+S and select Modules on the left.
Choose the required Ruby interpreter. You can also choose the gemset for the RVM and rbenv version managers.
For the selected Ruby interpreter/gemset, you can see the installed gems on the right. Learn more about Ruby gems support at Bundler.

Switch an interpreter using Run Anything

If you use RVM or rbenv to manage local Ruby SDKs, you can quickly set the required interpreter using Run Anything:

Press Ctrl twice.
In the invoked popup, start typing rvm use or rbenv shell, select the required interpreter and pressEnter.
(Optional) If necessary, click the Rollback button in the popup that informs about the changed SDK.

Add a remote interpreter

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 in IntelliJ IDEA and run, debug, and test your application in an isolated environment right from the IDE.

To configure a remote Ruby interpreter, follow these steps:

On the toolbar, click , and choose Remote Interpreter or Version Manager:
In the Configure Remote Ruby Interpreter dialog, select the desired option (SSH, Docker Compose, and so on) and specify the required settings.
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 button in the Ruby SDK and Gems page.
(Optional) Specify mappings between files of a local and remote project. To do this, click the button.
In the Edit Project Path Mappings dialog, specify the local and remote project root paths.
Note that IntelliJ IDEA detects Vagrant synced folders, WSL mappings, and so on. These mappings are listed in this dialog and cannot be changed.

Rename an interpreter

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

Open the Project Structure dialog Ctrl+Alt+Shift+S and select Modules on the left.
Right-click the required Ruby interpreter and select Edit name.
Alternatively, you can select the required Ruby interpreter and use the icon or press Enter.
In the Edit interpreter dialog, provide a new name for the interpreter and click OK.

Troubleshooting

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 SDK and Gems page is not displayed), try opening this project from existing sources.

From the main menu, select File | New | Project from existing sources.
Provide the path to your project.
In the Import Project dialog, select the Create project from existing sources option and click Next.
Specify the project name and path to the directory in which you want to create the project. Click Next.
Select the directories that you want to add to the project roots and click Next.
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 to configure a local interpreter.

Last modified: 24 January 2023