Ruby Shebang Directives in Binstubs
Last updated 16 July 2020
Table of Contents
A “shebang” line looks like this:
A binstub with a bad shebang can cause your application to function improperly. Here are a few examples of errors you might get if your application has a bad Ruby shebang line:
"Your Ruby version is 2.5.1, but your Gemfile specified 2.6.6"
"Activating bundler (>= 0.a) failed ... Could not find 'bundler' (>= 0.a)"
You have already activated bundler 1.17.2, but your Gemfile requires bundler 1.17.3
This article explains binstubs, shebang lines, and the common errors that come from improperly generated binstubs.
What is a Binstub?
A “binstub” is short for “binary stub”. It is a small script found in apps that is commonly generated by bundler or a web framework. The common convention in Ruby is to put any “binstubs” in the
bin/ directory of your application. Here is an example binstub from a Rails 6 project:
$ cat bin/rails #!/usr/bin/env ruby APP_PATH = File.expand_path('../config/application', __dir__) require_relative '../config/boot' require 'rails/commands'
The first line of the above binstub is:
This is known as a shebang line. It is a magic comment that tells unix-based operating systems how to execute your file. The preliminary
#! denotes that what follows is executable. Next,
/usr/bin/env provides an absolute path to the
env program of the unix operating system. Finally,
ruby is the name of the program that the script wants to use to execute. The combination of
/usr/bin/env ruby is essentially telling the operating system to use the
ruby executable that is first on the
Not all binstubs have to use Ruby. Common other langues are
Here’s several examples of Ruby shebang lines:
|Example Ruby shebang||Correct/Incorrect|
If the “shebang” line is malformed, references a non-existent binary, or a binary that is different than what you expect then your program will crash or behave in strange ways. This is an example of a common bad binstub:
This is a “bad” binstub because when you deploy an application to Heroku we install the Ruby binary on the PATH as
ruby and not as
ruby2.5. To make things more confusing, the Ubuntu operating system that Heroku uses (known as the “stack”) may have this executable on the path. For example on the Heroku-18 stack:
$ heroku run bash $ which ruby2.5 /usr/bin/ruby2.5
In this scenario, your application might be specifying you want to use Ruby 2.7.1 via the
Gemfile, but if your shebang line is using
ruby2.5 then it will be forced to use the wrong Ruby version. Usually, this bug causes a crash and a difficult to understand bundler error.
Correcting a bad shebang line
You can manually edit any incorrect “shebang” lines to read:
Once you’ve done this make sure to commit the results back to git:
$ git add . $ git commit -m "fixing shebang lines" $ git push heroku master
Why do binstubs exist in the Ruby ecosystem?
Files such as
bin/rails were introduced to the Ruby ecosystem to alleviate the verbose call of having to write out the full command
bundle exec rails. Instead, the script manually loads bundler and calls bundler setup before attempting to load a version of Rails. While that was the original intent of the files, they’re not limited to that functionality. For example prior versions also loaded up and configured the
spring gem which has historically caused problems, especially when related to a version of binstubs that contained a bug.
In addition to having a bad shebang line, your binstubs might contain bugs. Over time these files may change but since they’re generated by your initial
rails new <app-name> command they may be out of date. If you would like to update the binstubs on your rails project the command to do so is:
$ bin/rake app:update:bin exist bin identical bin/rails identical bin/rake conflict bin/setup Overwrite /app/bin/setup? (enter "h" for help) [Ynaqdhm] n skip bin/setup identical bin/yarn
Force bundler binstub generation
To prevent this issue from happening on your next docker based project generation you can set this in your Dockerfile before generating files:
This will not affect binstubs that have already been generated
The shebang line likely came from either Rails or bundler. Here’s a specific commit reference to a bundler template file:
#!/usr/bin/env <%= Bundler.settings[:shebang] || RbConfig::CONFIG["ruby_install_name"] %>
From this template bundler will try to find a customized “shebang” config, otherwise, it will execute the code
RbConfig::CONFIG["ruby_install_name"]. If you generated your project on a docker image or if your ruby installation was “named”. Then this might have been set for you:
$ docker run -it --rm heroku/heroku:18-build bash root@58980a533208:/# ruby -e 'puts RbConfig::CONFIG["ruby_install_name"]' ruby2.5