Skip to main content

Ruby versions on Bitrise


Ruby is pre-installed on all Bitrise stacks as several Steps require Ruby to work. You can change the active Ruby version by using a .ruby-version file or by using a Script Step.

Transition to Ruby 3.0 or higher before August 7, 2023

On Monday, August 7, 2023, Bitrise is removing all end-of-life Ruby versions from all Bitrise stacks. We strongly recommend transitioning to Ruby version 3.0 or higher as soon as possible and before Monday, August 7, 2023 at the latest. For more information, check out the official forum post.

Four official Bitrise Steps rely on Ruby to work. These are:

Third-party Steps

Third-party Steps - verified Steps and community Steps - that are not maintained by Bitrise might also use Ruby. Read more about the different Steps: Types of Steps.

Ruby is pre-installed on all our stacks. You can view the actual versions in the system reports. However, you can use a different Ruby version if that's what your app needs.

Managing Ruby versions in your builds

If you need a specific Ruby version, there are two main ways to make sure it will be installed on the virtual machine.

  • You can use a .ruby-version file. We recommend this method.

  • You can use a Script Step to override the Ruby version.

Using a .ruby-version file

The best way is to simply include the .ruby-version file in the root of your repository. The file should specify the version you need.

  • The Run CocoaPods Install Step looks for the .ruby-version file in the root of your repo. When you run the Step, it will install and activate the specified version. We plan to implement this feature for all Bitrise Steps that need Ruby.

  • Common version manager tools such as Ruby Version Manager, rbenv, or ASDF can read the file and automatically activate the specified version.

Setting up a version manager locally

If you set up one of the version manager tools locally, you can have a consistent setup between your local environment and the CI environment.

Using a Script Step

An alternative solution is to add a Script Step to your Workflow to override the default Ruby version. You can declare the version you want in the RUBY_VERSION Environment Variable and then use that Env Var with either rbenv or ASDF.


The method shown in the example relies on certain implementation details that are subject to change!

    - script:
        title: Activate correct Ruby version
        - content: |-
            set -ex
            # Configure rbenv by setting the RBENV_VERSION variable
            envman add --key RBENV_VERSION --value $RUBY_VERSION
            # Configure ASDF
            which asdf
            if [[ $? == 0 ]]; then
              asdf install ruby $RUBY_VERSION
              asdf global ruby $RUBY_VERSION

Supported Ruby versions

Before changing the Ruby version, make sure that the necessary tools support the version you need.

  • Fastlane supports Ruby 3 which means the Deploy to App Store Connect with Deliver and the fastlane Steps definitely support Ruby 3.

  • The recent versions of CocoaPods support Ruby 3. However, older legacy gems in your Gemfile or pods in your Podfile might not be compatible. Generally, we recommend always updating gems and pods to the latest version, and testing a Ruby version change in a local environment first.