Using rbenv on macOS Xcode Images

Overview

All CircleCI macOS Xcode images come with rbenv pre-installed, along with several recent Ruby versions. This setup makes it easy to select and use a specific Ruby version in your jobs without installing anything extra.

Description

rbenv is a Ruby version manager that allows you to easily switch between Ruby versions on the command line. In CircleCI’s macOS images, you can leverage the pre-installed versions and avoid having to compile Ruby manually, which saves time during builds.

How to Use rbenv in a macOS Job

To use a specific version of Ruby, set the version and rehash the shims:

version: 2.1

jobs:
  macos-build:
    macos:
      xcode: "16.2.0"
    steps:
      - checkout
      - run:
          name: Select Ruby version
          command: |
            rbenv versions
            rbenv global 3.2.2
            rbenv rehash
            ruby -v

Note: You can run rbenv versions to list available versions on the image.

Available Ruby Versions

Each macOS image may include different Ruby versions depending on the Xcode version. To verify the versions available in your current image:

rbenv versions

To see what’s included in a specific image, refer to our macOS image documentation.

Common Tips

• Use rbenv global to set the version for the session or rbenv local for per-project control.
• Run rbenv rehash after installing gems that provide CLI tools (e.g. fastlane).

Related Articles

• Using the macOS Execution Environment
• rbenv documentation on GitHub