1GEMFILE(5) GEMFILE(5)
2
6 Gemfile - A format for describing gem dependencies for Ruby programs
7
9 A Gemfile describes the gem dependencies required to execute associated
10 Ruby code.
11 Place the Gemfile in the root of the directory containing the associ‐
13 ated code. For instance, in a Rails application, place the Gemfile in
14 the same directory as the Rakefile.
15
17 A Gemfile is evaluated as Ruby code, in a context which makes available
18 a number of methods used to describe the gem requirements.
19
21 At the top of the Gemfile, add a single line for the RubyGems source
22 that contains the gems listed in the Gemfile.
23 source "https://rubygems.org"
27 You can add only one global source. In Bundler 1.13, adding multiple
31 global sources was deprecated. The source MUST be a valid RubyGems
32 repository.
33 To use more than one source of RubyGems, you should use source block.
35 A source is checked for gems following the heuristics described in
37 SOURCE PRIORITY.
38 Note about a behavior of the feature deprecated in Bundler 1.13: If a
40 gem is found in more than one global source, Bundler will print a warn‐
41 ing after installing the gem indicating which source was used, and
42 listing the other sources where the gem is available. A specific source
43 can be selected for gems that need to use a non-standard repository,
44 suppressing this warning, by using the :source option or source block.
45 CREDENTIALS
47 Some gem sources require a username and password. Use bundle config(1)
48 bundle-config.1.html to set the username and password for any of the
49 sources that need it. The command must be run once on each computer
50 that will install the Gemfile, but this keeps the credentials from be‐
51 ing stored in plain text in version control.
52 bundle config gems.example.com user:password
56 For some sources, like a company Gemfury account, it may be easier to
60 include the credentials in the Gemfile as part of the source URL.
61 source "https://user:password@gems.example.com"
65 Credentials in the source URL will take precedence over credentials set
69 using config.
70
72 If your application requires a specific Ruby version or engine, specify
73 your requirements using the ruby method, with the following arguments.
74 All parameters are OPTIONAL unless otherwise specified.
75 VERSION (required)
77 The version of Ruby that your application requires. If your application
78 requires an alternate Ruby engine, such as JRuby, TruffleRuby, etc.,
79 this should be the Ruby version that the engine is compatible with.
80 ruby "3.1.2"
84 ENGINE
88 Each application may specify a Ruby engine. If an engine is specified,
89 an engine version must also be specified.
90 What exactly is an Engine? - A Ruby engine is an implementation of the
92 Ruby language.
93 • For background: the reference or original implementation of the
95 Ruby programming language is called Matz´s Ruby Interpreter
96 https://en.wikipedia.org/wiki/Ruby_MRI, or MRI for short. This is
97 named after Ruby creator Yukihiro Matsumoto, also known as Matz.
98 MRI is also known as CRuby, because it is written in C. MRI is the
99 most widely used Ruby engine.
100 • Other implementations https://www.ruby-lang.org/en/about/ of Ruby
102 exist. Some of the more well-known implementations include JRuby
103 http://jruby.org/ and TruffleRuby https://www.graalvm.org/ruby/.
104 Rubinius is an alternative implementation of Ruby written in Ruby.
105 JRuby is an implementation of Ruby on the JVM, short for Java Vir‐
106 tual Machine. TruffleRuby is a Ruby implementation on the GraalVM,
107 a language toolkit built on the JVM.
108 ENGINE VERSION
112 Each application may specify a Ruby engine version. If an engine ver‐
113 sion is specified, an engine must also be specified. If the engine is
114 "ruby" the engine version specified must match the Ruby version.
115 ruby "2.6.8", engine: "jruby", engine_version: "9.3.8.0"
119 PATCHLEVEL
123 Each application may specify a Ruby patchlevel. Specifying the patch‐
124 level has been meaningless since Ruby 2.1.0 was released as the patch‐
125 level is now uniquely determined by a combination of major, minor, and
126 teeny version numbers.
127 This option was implemented in Bundler 1.4.0 for Ruby 2.0 or earlier.
129 ruby "3.1.2", patchlevel: "20"
133
137 Specify gem requirements using the gem method, with the following argu‐
138 ments. All parameters are OPTIONAL unless otherwise specified.
139 NAME (required)
141 For each gem requirement, list a single gem line.
142 gem "nokogiri"
146 VERSION
150 Each gem MAY have one or more version specifiers.
151 gem "nokogiri", ">= 1.4.2"
155 gem "RedCloth", ">= 4.1.0", "< 4.2.0"
156 REQUIRE AS
160 Each gem MAY specify files that should be used when autorequiring via
161 Bundler.require. You may pass an array with multiple files or true if
162 the file you want required has the same name as gem or false to prevent
163 any file from being autorequired.
164 gem "redis", require: ["redis/connection/hiredis", "redis"]
168 gem "webmock", require: false
169 gem "byebug", require: true
170 The argument defaults to the name of the gem. For example, these are
174 identical:
175 gem "nokogiri"
179 gem "nokogiri", require: "nokogiri"
180 gem "nokogiri", require: true
181 GROUPS
185 Each gem MAY specify membership in one or more groups. Any gem that
186 does not specify membership in any group is placed in the default
187 group.
188 gem "rspec", group: :test
192 gem "wirble", groups: [:development, :test]
193 The Bundler runtime allows its two main methods, Bundler.setup and
197 Bundler.require, to limit their impact to particular groups.
198 # setup adds gems to Ruby´s load path
202 Bundler.setup # defaults to all groups
203 require "bundler/setup" # same as Bundler.setup
204 Bundler.setup(:default) # only set up the _default_ group
205 Bundler.setup(:test) # only set up the _test_ group (but `not` _default_)
206 Bundler.setup(:default, :test) # set up the _default_ and _test_ groups, but no others
207 # require requires all of the gems in the specified groups
209 Bundler.require # defaults to the _default_ group
210 Bundler.require(:default) # identical
211 Bundler.require(:default, :test) # requires the _default_ and _test_ groups
212 Bundler.require(:test) # requires the _test_ group
213 The Bundler CLI allows you to specify a list of groups whose gems bun‐
217 dle install should not install with the without configuration.
218 To specify multiple groups to ignore, specify a list of groups sepa‐
220 rated by spaces.
221 bundle config set --local without test
225 bundle config set --local without development test
226 Also, calling Bundler.setup with no parameters, or calling require
230 "bundler/setup" will setup all groups except for the ones you excluded
231 via --without (since they are not available).
232 Note that on bundle install, bundler downloads and evaluates all gems,
234 in order to create a single canonical list of all of the required gems
235 and their dependencies. This means that you cannot list different ver‐
236 sions of the same gems in different groups. For more details, see Un‐
237 derstanding Bundler https://bundler.io/rationale.html.
238 PLATFORMS
240 If a gem should only be used in a particular platform or set of plat‐
241 forms, you can specify them. Platforms are essentially identical to
242 groups, except that you do not need to use the --without install-time
243 flag to exclude groups of gems for other platforms.
244 There are a number of Gemfile platforms:
246 ruby C Ruby (MRI), Rubinius, or TruffleRuby, but not Windows
248 mri C Ruby (MRI) only, but not Windows
250 windows
252 Windows C Ruby (MRI), including RubyInstaller 32-bit and 64-bit
253 versions
254 mswin Windows C Ruby (MRI), including RubyInstaller 32-bit versions
256 mswin64
258 Windows C Ruby (MRI), including RubyInstaller 64-bit versions
259 rbx Rubinius
261 jruby JRuby
263 truffleruby
265 TruffleRuby
266 On platforms ruby, mri, mswin, mswin64, and windows, you may addition‐
268 ally specify a version by appending the major and minor version numbers
269 without a delimiter. For example, to specify that a gem should only be
270 used on platform ruby version 3.1, use:
271 ruby_31
275 As with groups (above), you may specify one or more platforms:
279 gem "weakling", platforms: :jruby
283 gem "ruby-debug", platforms: :mri_31
284 gem "nokogiri", platforms: [:windows_31, :jruby]
285 All operations involving groups (bundle install bundle-install.1.html,
289 Bundler.setup, Bundler.require) behave exactly the same as if any
290 groups not matching the current platform were explicitly excluded.
291 FORCE_RUBY_PLATFORM
293 If you always want the pure ruby variant of a gem to be chosen over
294 platform specific variants, you can use the force_ruby_platform option:
295 gem "ffi", force_ruby_platform: true
299 This can be handy (assuming the pure ruby variant works fine) when:
303 • You´re having issues with the platform specific variant.
305 • The platform specific variant does not yet support a newer ruby
307 (and thus has a required_ruby_version upper bound), but you still
308 want your Gemfile{.lock} files to resolve under that ruby.
309 SOURCE
313 You can select an alternate RubyGems repository for a gem using the
314 ´:source´ option.
315 gem "some_internal_gem", source: "https://gems.example.com"
319 This forces the gem to be loaded from this source and ignores the
323 global source declared at the top level of the file. If the gem does
324 not exist in this source, it will not be installed.
325 Bundler will search for child dependencies of this gem by first looking
327 in the source selected for the parent, but if they are not found there,
328 it will fall back on the global source.
329 Note about a behavior of the feature deprecated in Bundler 1.13: Se‐
331 lecting a specific source repository this way also suppresses the am‐
332 biguous gem warning described above in GLOBAL SOURCE.
333 Using the :source option for an individual gem will also make that
335 source available as a possible global source for any other gems which
336 do not specify explicit sources. Thus, when adding gems with explicit
337 sources, it is recommended that you also ensure all other gems in the
338 Gemfile are using explicit sources.
339 GIT
341 If necessary, you can specify that a gem is located at a particular git
342 repository using the :git parameter. The repository can be accessed via
343 several protocols:
344 HTTP(S)
346 gem "rails", git: "https://github.com/rails/rails.git"
347 SSH gem "rails", git: "git@github.com:rails/rails.git"
349 git gem "rails", git: "git://github.com/rails/rails.git"
351 If using SSH, the user that you use to run bundle install MUST have the
353 appropriate keys available in their $HOME/.ssh.
354 NOTE: http:// and git:// URLs should be avoided if at all possible.
356 These protocols are unauthenticated, so a man-in-the-middle attacker
357 can deliver malicious code and compromise your system. HTTPS and SSH
358 are strongly preferred.
359 The group, platforms, and require options are available and behave ex‐
361 actly the same as they would for a normal gem.
362 A git repository SHOULD have at least one file, at the root of the di‐
364 rectory containing the gem, with the extension .gemspec. This file MUST
365 contain a valid gem specification, as expected by the gem build com‐
366 mand.
367 If a git repository does not have a .gemspec, bundler will attempt to
369 create one, but it will not contain any dependencies, executables, or C
370 extension compilation instructions. As a result, it may fail to prop‐
371 erly integrate into your application.
372 If a git repository does have a .gemspec for the gem you attached it
374 to, a version specifier, if provided, means that the git repository is
375 only valid if the .gemspec specifies a version matching the version
376 specifier. If not, bundler will print a warning.
377 gem "rails", "2.3.8", git: "https://github.com/rails/rails.git"
381 # bundle install will fail, because the .gemspec in the rails
382 # repository´s master branch specifies version 3.0.0
383 If a git repository does not have a .gemspec for the gem you attached
387 it to, a version specifier MUST be provided. Bundler will use this ver‐
388 sion in the simple .gemspec it creates.
389 Git repositories support a number of additional options.
391 branch, tag, and ref
393 You MUST only specify at most one of these options. The default
394 is branch: "master". For example:
395 gem "rails", git: "https://github.com/rails/rails.git", branch:
397 "5-0-stable"
398 gem "rails", git: "https://github.com/rails/rails.git", tag:
400 "v5.0.0"
401 gem "rails", git: "https://github.com/rails/rails.git", ref:
403 "4aded"
404 submodules
406 For reference, a git submodule
407 https://git-scm.com/book/en/v2/Git-Tools-Submodules lets you
408 have another git repository within a subfolder of your reposi‐
409 tory. Specify submodules: true to cause bundler to expand any
410 submodules included in the git repository
411 If a git repository contains multiple .gemspecs, each .gemspec repre‐
413 sents a gem located at the same place in the file system as the .gem‐
414 spec.
415 |~rails [git root]
419 | |-rails.gemspec [rails gem located here]
420 |~actionpack
421 | |-actionpack.gemspec [actionpack gem located here]
422 |~activesupport
423 | |-activesupport.gemspec [activesupport gem located here]
424 |...
425 To install a gem located in a git repository, bundler changes to the
429 directory containing the gemspec, runs gem build name.gemspec and then
430 installs the resulting gem. The gem build command, which comes standard
431 with Rubygems, evaluates the .gemspec in the context of the directory
432 in which it is located.
433 GIT SOURCE
435 A custom git source can be defined via the git_source method. Provide
436 the source´s name as an argument, and a block which receives a single
437 argument and interpolates it into a string to return the full repo ad‐
438 dress:
439 git_source(:stash){ |repo_name| "https://stash.corp.acme.pl/#{repo_name}.git" }
443 gem ´rails´, stash: ´forks/rails´
444 In addition, if you wish to choose a specific branch:
448 gem "rails", stash: "forks/rails", branch: "branch_name"
452 GITHUB
456 NOTE: This shorthand should be avoided until Bundler 2.0, since it cur‐
457 rently expands to an insecure git:// URL. This allows a man-in-the-mid‐
458 dle attacker to compromise your system.
459 If the git repository you want to use is hosted on GitHub and is pub‐
461 lic, you can use the :github shorthand to specify the github username
462 and repository name (without the trailing ".git"), separated by a
463 slash. If both the username and repository name are the same, you can
464 omit one.
465 gem "rails", github: "rails/rails"
469 gem "rails", github: "rails"
470 Are both equivalent to
474 gem "rails", git: "https://github.com/rails/rails.git"
478 Since the github method is a specialization of git_source, it accepts a
482 :branch named argument.
483 You can also directly pass a pull request URL:
485 gem "rails", github: "https://github.com/rails/rails/pull/43753"
489 Which is equivalent to:
493 gem "rails", github: "rails/rails", branch: "refs/pull/43753/head"
497 GIST
501 If the git repository you want to use is hosted as a GitHub Gist and is
502 public, you can use the :gist shorthand to specify the gist identifier
503 (without the trailing ".git").
504 gem "the_hatch", gist: "4815162342"
508 Is equivalent to:
512 gem "the_hatch", git: "https://gist.github.com/4815162342.git"
516 Since the gist method is a specialization of git_source, it accepts a
520 :branch named argument.
521 BITBUCKET
523 If the git repository you want to use is hosted on Bitbucket and is
524 public, you can use the :bitbucket shorthand to specify the bitbucket
525 username and repository name (without the trailing ".git"), separated
526 by a slash. If both the username and repository name are the same, you
527 can omit one.
528 gem "rails", bitbucket: "rails/rails"
532 gem "rails", bitbucket: "rails"
533 Are both equivalent to
537 gem "rails", git: "https://rails@bitbucket.org/rails/rails.git"
541 Since the bitbucket method is a specialization of git_source, it ac‐
545 cepts a :branch named argument.
546 PATH
548 You can specify that a gem is located in a particular location on the
549 file system. Relative paths are resolved relative to the directory con‐
550 taining the Gemfile.
551 Similar to the semantics of the :git option, the :path option requires
553 that the directory in question either contains a .gemspec for the gem,
554 or that you specify an explicit version that bundler should use.
555 Unlike :git, bundler does not compile C extensions for gems specified
557 as paths.
558 gem "rails", path: "vendor/rails"
562 If you would like to use multiple local gems directly from the filesys‐
566 tem, you can set a global path option to the path containing the gem´s
567 files. This will automatically load gemspec files from subdirectories.
568 path ´components´ do
572 gem ´admin_ui´
573 gem ´public_ui´
574 end
575
579 The :source, :git, :path, :group, and :platforms options may be applied
580 to a group of gems by using block form.
581 source "https://gems.example.com" do
585 gem "some_internal_gem"
586 gem "another_internal_gem"
587 end
588 git "https://github.com/rails/rails.git" do
590 gem "activesupport"
591 gem "actionpack"
592 end
593 platforms :ruby do
595 gem "ruby-debug"
596 gem "sqlite3"
597 end
598 group :development, optional: true do
600 gem "wirble"
601 gem "faker"
602 end
603 In the case of the group block form the :optional option can be given
607 to prevent a group from being installed unless listed in the --with op‐
608 tion given to the bundle install command.
609 In the case of the git block form, the :ref, :branch, :tag, and :sub‐
611 modules options may be passed to the git method, and all gems in the
612 block will inherit those options.
613 The presence of a source block in a Gemfile also makes that source
615 available as a possible global source for any other gems which do not
616 specify explicit sources. Thus, when defining source blocks, it is rec‐
617 ommended that you also ensure all other gems in the Gemfile are using
618 explicit sources, either via source blocks or :source directives on in‐
619 dividual gems.
620
622 The install_if method allows gems to be installed based on a proc or
623 lambda. This is especially useful for optional gems that can only be
624 used if certain software is installed or some other conditions are met.
625 install_if -> { RUBY_PLATFORM =~ /darwin/ } do
629 gem "pasteboard"
630 end
631
635 The .gemspec http://guides.rubygems.org/specification-reference/ file
636 is where you provide metadata about your gem to Rubygems. Some required
637 Gemspec attributes include the name, description, and homepage of your
638 gem. This is also where you specify the dependencies your gem needs to
639 run.
640 If you wish to use Bundler to help install dependencies for a gem while
642 it is being developed, use the gemspec method to pull in the dependen‐
643 cies listed in the .gemspec file.
644 The gemspec method adds any runtime dependencies as gem requirements in
646 the default group. It also adds development dependencies as gem re‐
647 quirements in the development group. Finally, it adds a gem requirement
648 on your project (path: ´.´). In conjunction with Bundler.setup, this
649 allows you to require project files in your test code as you would if
650 the project were installed as a gem; you need not manipulate the load
651 path manually or require project files via relative paths.
652 The gemspec method supports optional :path, :glob, :name, and :develop‐
654 ment_group options, which control where bundler looks for the .gemspec,
655 the glob it uses to look for the gemspec (defaults to: "{,,/*}.gem‐
656 spec"), what named .gemspec it uses (if more than one is present), and
657 which group development dependencies are included in.
658 When a gemspec dependency encounters version conflicts during resolu‐
660 tion, the local version under development will always be selected --
661 even if there are remote versions that better match other requirements
662 for the gemspec gem.
663
665 When attempting to locate a gem to satisfy a gem requirement, bundler
666 uses the following priority order:
667 1. The source explicitly attached to the gem (using :source, :path, or
669 :git)
670 2. For implicit gems (dependencies of explicit gems), any source, git,
672 or path repository declared on the parent. This results in bundler
673 prioritizing the ActiveSupport gem from the Rails git repository
674 over ones from rubygems.org
675 3. If neither of the above conditions are met, the global source will
677 be used. If multiple global sources are specified, they will be
678 prioritized from last to first, but this is deprecated since
679 Bundler 1.13, so Bundler prints a warning and will abort with an
680 error in the future.
681 February 2023 GEMFILE(5)