1GEMFILE(5)                                                          GEMFILE(5)
2
3
4

NAME

6       Gemfile - A format for describing gem dependencies for Ruby programs
7

SYNOPSIS

9       A Gemfile describes the gem dependencies required to execute associated
10       Ruby code.
11
12       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

SYNTAX

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

GLOBAL SOURCE

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
24
25
26           source "https://rubygems.org"
27
28
29
30       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
34       To use more than one source of RubyGems, you should use source block.
35
36       A source is checked for gems  following  the  heuristics  described  in
37       SOURCE PRIORITY.
38
39       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
46   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
53
54
55           bundle config gems.example.com user:password
56
57
58
59       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
62
63
64           source "https://user:password@gems.example.com"
65
66
67
68       Credentials in the source URL will take precedence over credentials set
69       using config.
70

RUBY

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
76   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
81
82
83           ruby "3.1.2"
84
85
86
87   ENGINE
88       Each application may specify a Ruby engine. If an engine is  specified,
89       an engine version must also be specified.
90
91       What  exactly is an Engine? - A Ruby engine is an implementation of the
92       Ruby language.
93
94       •   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
101       •   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
109
110
111   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
116
117
118           ruby "2.6.8", engine: "jruby", engine_version: "9.3.8.0"
119
120
121
122   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
128       This option was implemented in Bundler 1.4.0 for Ruby 2.0 or earlier.
129
130
131
132           ruby "3.1.2", patchlevel: "20"
133
134
135

GEMS

137       Specify gem requirements using the gem method, with the following argu‐
138       ments. All parameters are OPTIONAL unless otherwise specified.
139
140   NAME (required)
141       For each gem requirement, list a single gem line.
142
143
144
145           gem "nokogiri"
146
147
148
149   VERSION
150       Each gem MAY have one or more version specifiers.
151
152
153
154           gem "nokogiri", ">= 1.4.2"
155           gem "RedCloth", ">= 4.1.0", "< 4.2.0"
156
157
158
159   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
165
166
167           gem "redis", require: ["redis/connection/hiredis", "redis"]
168           gem "webmock", require: false
169           gem "byebug", require: true
170
171
172
173       The argument defaults to the name of the gem. For  example,  these  are
174       identical:
175
176
177
178           gem "nokogiri"
179           gem "nokogiri", require: "nokogiri"
180           gem "nokogiri", require: true
181
182
183
184   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
189
190
191           gem "rspec", group: :test
192           gem "wirble", groups: [:development, :test]
193
194
195
196       The  Bundler  runtime  allows  its  two main methods, Bundler.setup and
197       Bundler.require, to limit their impact to particular groups.
198
199
200
201           # 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
208           # 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
214
215
216       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
219       To  specify  multiple  groups to ignore, specify a list of groups sepa‐
220       rated by spaces.
221
222
223
224           bundle config set --local without test
225           bundle config set --local without development test
226
227
228
229       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
233       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
239   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
245       There are a number of Gemfile platforms:
246
247       ruby   C Ruby (MRI), Rubinius, or TruffleRuby, but not Windows
248
249       mri    C Ruby (MRI) only, but not Windows
250
251       windows
252              Windows  C Ruby (MRI), including RubyInstaller 32-bit and 64-bit
253              versions
254
255       mswin  Windows C Ruby (MRI), including RubyInstaller 32-bit versions
256
257       mswin64
258              Windows C Ruby (MRI), including RubyInstaller 64-bit versions
259
260       rbx    Rubinius
261
262       jruby  JRuby
263
264       truffleruby
265              TruffleRuby
266
267       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
272
273
274           ruby_31
275
276
277
278       As with groups (above), you may specify one or more platforms:
279
280
281
282           gem "weakling",   platforms: :jruby
283           gem "ruby-debug", platforms: :mri_31
284           gem "nokogiri",   platforms: [:windows_31, :jruby]
285
286
287
288       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
292   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
296
297
298           gem "ffi", force_ruby_platform: true
299
300
301
302       This can be handy (assuming the pure ruby variant works fine) when:
303
304       •   You´re having issues with the platform specific variant.
305
306       •   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
310
311
312   SOURCE
313       You can select an alternate RubyGems repository for  a  gem  using  the
314       ´:source´ option.
315
316
317
318           gem "some_internal_gem", source: "https://gems.example.com"
319
320
321
322       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
326       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
330       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
334       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
340   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
345       HTTP(S)
346              gem "rails", git: "https://github.com/rails/rails.git"
347
348       SSH    gem "rails", git: "git@github.com:rails/rails.git"
349
350       git    gem "rails", git: "git://github.com/rails/rails.git"
351
352       If using SSH, the user that you use to run bundle install MUST have the
353       appropriate keys available in their $HOME/.ssh.
354
355       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
360       The  group, platforms, and require options are available and behave ex‐
361       actly the same as they would for a normal gem.
362
363       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
368       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
373       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
378
379
380           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
384
385
386       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
390       Git repositories support a number of additional options.
391
392       branch, tag, and ref
393              You  MUST only specify at most one of these options. The default
394              is branch: "master". For example:
395
396              gem "rails", git: "https://github.com/rails/rails.git",  branch:
397              "5-0-stable"
398
399              gem  "rails",  git:  "https://github.com/rails/rails.git",  tag:
400              "v5.0.0"
401
402              gem  "rails",  git:  "https://github.com/rails/rails.git",  ref:
403              "4aded"
404
405       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
412       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
416
417
418           |~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
426
427
428       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
434   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
440
441
442           git_source(:stash){ |repo_name| "https://stash.corp.acme.pl/#{repo_name}.git" }
443           gem ´rails´, stash: ´forks/rails´
444
445
446
447       In addition, if you wish to choose a specific branch:
448
449
450
451           gem "rails", stash: "forks/rails", branch: "branch_name"
452
453
454
455   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
460       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
466
467
468           gem "rails", github: "rails/rails"
469           gem "rails", github: "rails"
470
471
472
473       Are both equivalent to
474
475
476
477           gem "rails", git: "https://github.com/rails/rails.git"
478
479
480
481       Since the github method is a specialization of git_source, it accepts a
482       :branch named argument.
483
484       You can also directly pass a pull request URL:
485
486
487
488           gem "rails", github: "https://github.com/rails/rails/pull/43753"
489
490
491
492       Which is equivalent to:
493
494
495
496           gem "rails", github: "rails/rails", branch: "refs/pull/43753/head"
497
498
499
500   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
505
506
507           gem "the_hatch", gist: "4815162342"
508
509
510
511       Is equivalent to:
512
513
514
515           gem "the_hatch", git: "https://gist.github.com/4815162342.git"
516
517
518
519       Since  the  gist method is a specialization of git_source, it accepts a
520       :branch named argument.
521
522   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
529
530
531           gem "rails", bitbucket: "rails/rails"
532           gem "rails", bitbucket: "rails"
533
534
535
536       Are both equivalent to
537
538
539
540           gem "rails", git: "https://rails@bitbucket.org/rails/rails.git"
541
542
543
544       Since the bitbucket method is a specialization of  git_source,  it  ac‐
545       cepts a :branch named argument.
546
547   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
552       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
556       Unlike  :git,  bundler does not compile C extensions for gems specified
557       as paths.
558
559
560
561           gem "rails", path: "vendor/rails"
562
563
564
565       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
569
570
571           path ´components´ do
572             gem ´admin_ui´
573             gem ´public_ui´
574           end
575
576
577

BLOCK FORM OF SOURCE, GIT, PATH, GROUP and PLATFORMS

579       The :source, :git, :path, :group, and :platforms options may be applied
580       to a group of gems by using block form.
581
582
583
584           source "https://gems.example.com" do
585             gem "some_internal_gem"
586             gem "another_internal_gem"
587           end
588
589           git "https://github.com/rails/rails.git" do
590             gem "activesupport"
591             gem "actionpack"
592           end
593
594           platforms :ruby do
595             gem "ruby-debug"
596             gem "sqlite3"
597           end
598
599           group :development, optional: true do
600             gem "wirble"
601             gem "faker"
602           end
603
604
605
606       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
610       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
614       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

INSTALL_IF

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
626
627
628           install_if -> { RUBY_PLATFORM =~ /darwin/ } do
629             gem "pasteboard"
630           end
631
632
633

GEMSPEC

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
641       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
645       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
653       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
659       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

SOURCE PRIORITY

665       When  attempting  to locate a gem to satisfy a gem requirement, bundler
666       uses the following priority order:
667
668       1.  The source explicitly attached to the gem (using :source, :path, or
669           :git)
670
671       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
676       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
682
683
684
685
686
687                                 February 2023                      GEMFILE(5)
Impressum