IntelliJ IDEA
 
2025.1
Shortcuts: Windows
Get IntelliJ IDEA
  1. Non-JVM technologies
  2. Ruby
  3. Bundler
Ultimate

Bundler

Last modified: 07 March 2025

Required plugin: Ruby

IntelliJ IDEA supports integration with Bundler and enables you to handle gem dependencies for your application right inside the IDE.

Install Bundler

As a rule, the installed Ruby interpreter comes with Bundler installed. If not, you can install Bundler to the project interpreter in one of the following ways:

  • Select Tools | Bundler | Install Bundler from the main menu.

  • Press Ctrl twice and execute the gem install bundler command in the invoked popup.

  • Open the IntelliJ IDEA terminal emulator and execute the gem install bundler command.

tip

You can also install the Bundler gem along with other gems from the Gemfile.

Bundle init

After installing Bundler, you can generate a Gemfile for the current project:

  • Select Tools | Bundler | Init from the main menu.

tip

Creating a new Rails application initializes Bundler automatically since Rails has support for Bundler.

Install gems

You can install gems defined in the Gemfile to the project interpreter as follows:

  1. Do one of the following:

    • Press Ctrl twice. In the invoked popup, start typing bundler, select bundle install and press Enter.

    • Select Tools | Bundler | Install from the main menu.

    • Open the Gemfile, place the caret at any highlighted gem missing in the project interpreter and press AltEnter. Select Install missing gems using 'bundler' and press Enter.

      Gemfile inspection

  2. (Optional) If the current project interpreter does not have the required Bundler version specified in Gemfile.lock, IntelliJ IDEA suggests installing it.

  3. In the Bundle Install dialog, click Install to run the bundle install command without any arguments.

    Bundle Install dialog

    If necessary, pass the required arguments when running this command, for example:

    • --without production: install all gems except ones mentioned in the production group within the Gemfile.

    • --path vendor/bundle: install gems to the vendor/bundle project directory. In this case, Bundler adds the .bundle/config file to a project’s root. IntelliJ IDEA processes this configuration file to detect that gems are installed into vendor/bundle.

  4. Wait until gems are installed. The Run tool window will display this process:

    Bundler output

    You can see the installed gems in the Project Settings | Modules | Ruby SDK and Gems CtrlAltShift0S page.

    Ruby SDK and Gems page

    And you can also find them in the External Libraries node of the Project view Alt01.

    External libraries

Install gems to a remote interpreter

If you are using a remote Ruby interpreter, IntelliJ IDEA uses the Gemfile placed on a remote machine to install the gems. This requires configuring mappings between files of a local and remote project. To do this, click the Edit Path Mappings Edit Path Mappings button in Project Settings | Modules | Ruby SDK and Gems.

Ruby SDK and Gems page

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

Edit project path mappings

After you configured mappings, install gems using the Install Gems to Local Interpreter instruction.

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 button in the Ruby Interpreters page.

Bundle exec

IntelliJ IDEA provides the capability to run and debug Ruby and Rails applications, run tests, and deploy your code in a universal way - by using run/debug configurations. Run/debug configurations provide the default set of startup parameters that allow you to run the desired command quickly. You can execute any of these commands in the context of the bundle in the following way:

  1. Open the Run/Debug Configuration dialog in one of the following ways:

    • Select Run | Edit Configurations from the main menu.

    • With the Navigation bar visible (View | Appearance | Navigation Bar), choose Edit Configurations from the run/debug configuration selector.

    • Press AltShiftF10 and then press 00.

  2. In the opened Run/Debug Configurations dialog, select the required configuration and open the Bundler tab.

  3. Configure the Run the script in the context of the bundle ('bundle exec') option:

    • Auto-detection: select this option to run your code with bundle exec when it is possible.

      note

      When the Auto-detection option is enabled, IntelliJ IDEA checks whether the following conditions are met:

      • Gemfile and Gemfile.lock are present

      • The version of the bundler gem specified in Gemfile.lock is also installed in the run/debug configuration's interpreter

      In case either of these conditions isn't met, the executed command will remain without any changes.

    • Disabled: select this option to disable the use of bundle exec.

    Click OK.

Run bundle check in dry mode

IntelliJ IDEA provides an option to run bundle check in dry mode. In this case, Bundler will not create or update your lockfile.

  1. In the main menu, go to Help | Find Action CtrlShift0A.

  2. Start typing Run silent bundle check with --dry-run. Select the option and press Enter to enable it.

    Enabling dry mode

    Once you've enabled this option, you will need to maintain your lockfile yourself. After changing your Gemfile, run bundle check/bundle lock to update your lockfile.