Better iOS projects: How to manage the ruby environment of your iOS project using rbenv
In the series "Better iOS projects", we have a look at the various tools and environments that are useful to have a more convenient and efficient handling of iOS Projects.Mai 22, 2018, by Wolfgang Lutz
Managing rubies is easier with rbenv.
You should not have to use root user permissions via sudo for any of the installs that follow. If you seem to need to, you most likely already had a permission problem before or you did not install and setup rbenv correctly.
How to manage the ruby environment of your iOS Project using rbenv
Why do we want to do this?
macOS comes with an older version of ruby preinstalled by default. As the system uses ruby itself, it is best practice not to mess around with the system ruby and use a user-installed (and more up-to-date) version of the ruby language. A ruby version manager allows you to maintain multiple installs of different ruby versions at the same time and decide per project (automatically via the .ruby-version file) which version of ruby you want to use.
A glossary of tools and filenames used in this article is available at the end of this article.
Which ruby environment manager should I use?
Install and setup rbenv
rbenv can easily be installed using the brew package manager, so make sure you have it installed and running.
install rbenv and ruby-build using brew
Install rbenv (for managing ruby environments) by running
brew install rbenv
this will also install ruby-build tool (for installing versions of ruby via rbenv)
If you are upgrading run
brew upgrade rbenv ruby-build
setup rbenv for your shell
After installing the tools above, you need to add a call to setup rbenv to your shell's configuration script.
You can find out which shell you are using by calling
Depending on the result, you need to either change _~/.bash_profile (for bash), ~/.zshrc_ (for zsh) or the corresponding file of your shell if you have another shell.
If the file (e.g. _~/.bash_profile_) does not exist before, just create it.
As we use the very good Oh-My-ZSH as shell, we can edit it by opening ~/.zshrc in a graphical text editor or edit it directly in the shell by calling
eval "$(rbenv init -)"
to the end of the file and save it, then quit your terminal application and reopen it to make sure the changes are applied.
rbenv has various commands, which should be listed when you run
The most important for us in the scope of this article are:
This shows the current ruby version set via rbenv. By default, this should show system. It also shows you the path to the file that is responsible for selecting the version.
This lists all versions of ruby installed via rbenv (and the system version).
Installs a specific version of ruby. You can look up the newest version of ruby at ruby-lang.org.
rbenv install -l shows you a list of versions available to ruby-build. If you are
missing a version, upgrade ruby-build by running
brew upgrade rbenv ruby-build.
This shows or sets the version defined for the current directory and its subdirectories.
This can become handy if you have trouble using a gem after having it installed, as it updates the underpinnings of rbenv.
rbenv which and rbenv whence are useful if you have issues when using ruby via rbenv and something does not work as expected.
Install a custom ruby and create the .ruby-version file
Start by installing the newest version, which is 2.5.1 at the time of this post:
rbenv install 2.5.1
See https://www.ruby-lang.org/en/downloads/ for the most recent version.
If there already is a .ruby-version file, run
without any version argument to install the version set in the .ruby-version file.
Enter your iOS project directory and run
rbenv local 2.5.1
to create a .ruby-version file with the content
rbenv local will only do this, if the version is already installed.
After restarting the terminal (or entering the parent directory and reentering the directory), running
version should give you the version
2.5.1 if everything worked correctly.
How to use Bundler
What is Bundler?
bundler is a dependency manager for ruby, as cocoapods is for the iOS ecosystem. It can ensure that a defined set of dependencies is installed with the exact version of dependencies (gems) that was used when the dependencies where updated the last time.
How to install bundler
For every ruby version installed via rbenv, you have to once run
gem install bundler
to install the dependency manager.
What files does Bundler use?
Bundler defines dependencies using a Gemfile.
This defines, what gems (and possibly: what versions) you want to have installed:
# List of gems used in this project gem "cocoapods", "~> 1.5"
When updating gems (or adding them to the project), the exact version of the gem that will be installed is written to a file named Gemfile.lock.
Adding and updating gems
When you do not have a Gemfile yet, you can create one by running
To add a first dependency, you can run
bundle add <Gemname>, e.g.
bundle add fastlane
This adds the dependency to the Gemfile and installs the new dependency.
resolves the dependency graph in the Gemfile, installs the dependencies and writes the resolved versions to the Gemfile.lock file. This is important if you edit the Gemfile by hand.
You should now be able to run
bundle exec fastlane
if everything went right.
To sync the dependencies across the developers of the project, it is important to commit both Gemfile and Gemfile.lock to your project.
When do I need to run bundle install and bundle update?
Generally, you only need to run
bundle update if you really intend to upgrade the versions of your
When you check out a project and want to get it to build, it is sufficient to run
bundle install most
of the time.
Where to go from here?
Install and properly manage the gems your project needs and at least teach your team how to install new ruby versions via rbenv and gems via bundle.
In the next post of the "Better iOS Projects" series, we have a look at some advanced features of rbenv.
- .ruby-version: a simple file that defines, what version of ruby you want to use for the project
- bash: The default shell for most Linux and UNIX systems, see BASH
- bundler: the ruby dependency manager
- gem: a ruby dependency
- Gemfile: the definition file, where all the dependencies are listed that bundler should install
- Gemfile.lock: the file, where bundler saves the exact versions of all dependencies and their dependencies, as resolved during install
- oh-my-zsh: a collection of configurations and scripts for zsh
- rbenv: a tool to manage multiple versions of ruby on the same computer
- ruby-build: a tool to install ruby versions
- ruby: a programming language
- zsh: the Z Shell
Thanks to Melanie Kloss for the great banner image.