1BUNDLE-INSTALL(1)                                            BUNDLE-INSTALL(1)
2
3
4

NAME

6       bundle-install - Install the dependencies specified in your Gemfile
7

SYNOPSIS

9       bundle   install   [--binstubs[=DIRECTORY]]   [--clean]  [--deployment]
10       [--frozen] [--full-index] [--gemfile=GEMFILE] [--jobs=NUMBER] [--local]
11       [--no-cache]   [--no-prune]   [--path  PATH]  [--quiet]  [--redownload]
12       [--retry=NUMBER] [--shebang] [--standalone[=GROUP[ GROUP...]]]  [--sys‐
13       tem]   [--trust-policy=POLICY]   [--with=GROUP[   GROUP...]]   [--with‐
14       out=GROUP[ GROUP...]]
15

DESCRIPTION

17       Install the gems specified in your Gemfile(5). If  this  is  the  first
18       time  you  run  bundle  install  (and  a  Gemfile.lock does not exist),
19       Bundler will fetch all remote sources, resolve dependencies and install
20       all needed gems.
21
22       If a Gemfile.lock does exist, and you have not updated your Gemfile(5),
23       Bundler will fetch all remote sources, but use the dependencies  speci‐
24       fied in the Gemfile.lock instead of resolving dependencies.
25
26       If  a  Gemfile.lock  does  exist, and you have updated your Gemfile(5),
27       Bundler will use the dependencies in the Gemfile.lock for all gems that
28       you  did  not update, but will re-resolve the dependencies of gems that
29       you did update. You can find more information about this update process
30       below under CONSERVATIVE UPDATING.
31

OPTIONS

33       The  --clean,  --deployment,  --frozen,  --no-prune, --path, --shebang,
34       --system, --without and --with options are deprecated because they only
35       make  sense  if they are applied to every subsequent bundle install run
36       automatically and that requires  bundler  to  silently  remember  them.
37       Since  bundler  will  no  longer remember CLI flags in future versions,
38       bundle config (see bundle-config(1)) should be used to apply them  per‐
39       manently.
40
41       --binstubs[=<directory>]
42              Binstubs  are scripts that wrap around executables. Bundler cre‐
43              ates a small Ruby file (a binstub) that loads Bundler, runs  the
44              command, and puts it in bin/. This lets you link the binstub in‐
45              side of an application to the exact gem version the  application
46              needs.
47
48              Creates  a directory (defaults to ~/bin) and places any executa‐
49              bles from the gem there. These executables run in Bundler´s con‐
50              text.  If  used,  you  might add this directory to your environ‐
51              ment´s PATH variable. For instance, if the rails gem comes  with
52              a rails executable, this flag will create a bin/rails executable
53              that ensures that all referred dependencies will be resolved us‐
54              ing the bundled gems.
55
56       --clean
57              On  finishing  the  installation  Bundler is going to remove any
58              gems not present in the current Gemfile(5).  Don´t  worry,  gems
59              currently in use will not be removed.
60
61              This option is deprecated in favor of the clean setting.
62
63       --deployment
64              In  deployment mode, Bundler will ´roll-out´ the bundle for pro‐
65              duction or CI use. Please check carefully if you  want  to  have
66              this option enabled in your development environment.
67
68              This option is deprecated in favor of the deployment setting.
69
70       --redownload
71              Force  download every gem, even if the required versions are al‐
72              ready available locally.
73
74       --frozen
75              Do not allow the Gemfile.lock to be updated after this  install.
76              Exits  non-zero  if  there  are  going to be changes to the Gem‐
77              file.lock.
78
79              This option is deprecated in favor of the frozen setting.
80
81       --full-index
82              Bundler will not call Rubygems´ API endpoint (default) but down‐
83              load and cache a (currently big) index file of all gems. Perfor‐
84              mance can be improved for large bundles that  seldom  change  by
85              enabling this option.
86
87       --gemfile=<gemfile>
88              The  location  of  the Gemfile(5) which Bundler should use. This
89              defaults to a Gemfile(5) in the current  working  directory.  In
90              general, Bundler will assume that the location of the Gemfile(5)
91              is also the project´s root and will try to find Gemfile.lock and
92              vendor/cache relative to this location.
93
94       --jobs=[<number>], -j[<number>]
95              The  maximum  number  of parallel download and install jobs. The
96              default is 1.
97
98       --local
99              Do not attempt to connect to rubygems.org. Instead, Bundler will
100              use  the  gems  already  present  in  Rubygems´ cache or in ven‐
101              dor/cache. Note that if an appropriate platform-specific gem ex‐
102              ists on rubygems.org it will not be found.
103
104       --no-cache
105              Do  not  update the cache in vendor/cache with the newly bundled
106              gems. This does not remove any gems in the cache but  keeps  the
107              newly bundled gems from being cached during the install.
108
109       --no-prune
110              Don´t  remove  stale  gems  from the cache when the installation
111              finishes.
112
113              This option is deprecated in favor of the no_prune setting.
114
115       --path=<path>
116              The location to install the specified gems to. This defaults  to
117              Rubygems´  setting.  Bundler shares this location with Rubygems,
118              gem install ... will have gem installed there,  too.  Therefore,
119              gems  installed  without  a  --path  ... setting will show up by
120              calling gem list. Accordingly, gems installed to other locations
121              will not get listed.
122
123              This option is deprecated in favor of the path setting.
124
125       --quiet
126              Do  not  print  progress information to the standard output. In‐
127              stead, Bundler will exit using a status code ($?).
128
129       --retry=[<number>]
130              Retry failed network or git requests for number times.
131
132       --shebang=<ruby-executable>
133              Uses the specified ruby executable (usually ruby) to execute the
134              scripts  created with --binstubs. In addition, if you use --bin‐
135              stubs together with --shebang jruby these  executables  will  be
136              changed to execute jruby instead.
137
138              This option is deprecated in favor of the shebang setting.
139
140       --standalone[=<list>]
141              Makes  a  bundle  that can work without depending on Rubygems or
142              Bundler at runtime. A space separated list of groups to  install
143              has  to  be  specified. Bundler creates a directory named bundle
144              and  installs  the  bundle  there.  It  also  generates  a  bun‐
145              dle/bundler/setup.rb  file to replace Bundler´s own setup in the
146              manner required. Using this option implicitly sets  path,  which
147              is a [remembered option][REMEMBERED OPTIONS].
148
149       --system
150              Installs  the  gems  specified  in  the  bundle  to the system´s
151              Rubygems location. This overrides any previous configuration  of
152              --path.
153
154              This option is deprecated in favor of the system setting.
155
156       --trust-policy=[<policy>]
157              Apply  the  Rubygems security policy policy, where policy is one
158              of HighSecurity, MediumSecurity, LowSecurity,  AlmostNoSecurity,
159              or NoSecurity. For more details, please see the Rubygems signing
160              documentation linked below in SEE ALSO.
161
162       --with=<list>
163              A space-separated list of groups referencing gems to install. If
164              an  optional group is given it is installed. If a group is given
165              that is in the remembered list of groups given to --without,  it
166              is removed from that list.
167
168              This option is deprecated in favor of the with setting.
169
170       --without=<list>
171              A space-separated list of groups referencing gems to skip during
172              installation. If a group is given that is in the remembered list
173              of groups given to --with, it is removed from that list.
174
175              This option is deprecated in favor of the without setting.
176

DEPLOYMENT MODE

178       Bundler´s defaults are optimized for development. To switch to defaults
179       optimized for deployment and for CI, use the --deployment flag. Do  not
180       activate  deployment  mode on development machines, as it will cause an
181       error when the Gemfile(5) is modified.
182
183       1.  A Gemfile.lock is required.
184
185           To ensure that the same versions of the gems you developed with and
186           tested  with  are  also  used in deployments, a Gemfile.lock is re‐
187           quired.
188
189           This is mainly to ensure that  you  remember  to  check  your  Gem‐
190           file.lock into version control.
191
192       2.  The Gemfile.lock must be up to date
193
194           In  development,  you  can modify your Gemfile(5) and re-run bundle
195           install to conservatively update your Gemfile.lock snapshot.
196
197           In deployment, your Gemfile.lock should be up-to-date with  changes
198           made in your Gemfile(5).
199
200       3.  Gems  are  installed to vendor/bundle not your default system loca‐
201           tion
202
203           In development, it´s convenient to share the gems used in your  ap‐
204           plication with other applications and other scripts that run on the
205           system.
206
207           In deployment, isolation is a more important default. In  addition,
208           the  user  deploying the application may not have permission to in‐
209           stall gems to the system, or the web server may not have permission
210           to read them.
211
212           As  a result, bundle install --deployment installs gems to the ven‐
213           dor/bundle directory in the application. This may be overridden us‐
214           ing the --path option.
215
216
217

SUDO USAGE

219       By default, Bundler installs gems to the same location as gem install.
220
221       In  some cases, that location may not be writable by your Unix user. In
222       that case, Bundler will stage everything in a temporary directory, then
223       ask  you  for  your  sudo password in order to copy the gems into their
224       system location.
225
226       From your perspective, this is identical to  installing  the  gems  di‐
227       rectly into the system.
228
229       You should never use sudo bundle install. This is because several other
230       steps in bundle install must be performed as the current user:
231
232       •   Updating your Gemfile.lock
233
234       •   Updating your vendor/cache, if necessary
235
236       •   Checking out private git repositories using your user´s SSH keys
237
238
239
240       Of these three, the first  two  could  theoretically  be  performed  by
241       chowning  the  resulting  files  to $SUDO_USER. The third, however, can
242       only be performed by invoking the git  command  as  the  current  user.
243       Therefore,  git gems are downloaded and installed into ~/.bundle rather
244       than $GEM_HOME or $BUNDLE_PATH.
245
246       As a result, you should run bundle install as  the  current  user,  and
247       Bundler will ask for your password if it is needed to put the gems into
248       their final location.
249

INSTALLING GROUPS

251       By default, bundle install will install all gems in all groups in  your
252       Gemfile(5), except those declared for a different platform.
253
254       However,  you  can  explicitly  tell Bundler to skip installing certain
255       groups with the --without option. This option takes  a  space-separated
256       list of groups.
257
258       While  the --without option will skip installing the gems in the speci‐
259       fied groups, it will still download those gems and use them to  resolve
260       the dependencies of every gem in your Gemfile(5).
261
262       This is so that installing a different set of groups on another machine
263       (such as a production server) will not change  the  gems  and  versions
264       that you have already developed and tested against.
265
266       Bundler offers a rock-solid guarantee that the third-party code you are
267       running in development and testing is also the third-party code you are
268       running  in  production. You can choose to exclude some of that code in
269       different environments, but you will never  be  caught  flat-footed  by
270       different versions of third-party code being used in different environ‐
271       ments.
272
273       For a simple illustration, consider the following Gemfile(5):
274
275
276
277           source ´https://rubygems.org´
278
279           gem ´sinatra´
280
281           group :production do
282             gem ´rack-perftools-profiler´
283           end
284
285
286
287       In this case, sinatra depends on any version of Rack  (>=  1.0),  while
288       rack-perftools-profiler depends on 1.x (~> 1.0).
289
290       When  you  run  bundle  install --without production in development, we
291       look at the dependencies of rack-perftools-profiler as well. That  way,
292       you  do  not spend all your time developing against Rack 2.0, using new
293       APIs unavailable in Rack 1.x, only to have Bundler switch to  Rack  1.2
294       when the production group is used.
295
296       This  should  not cause any problems in practice, because we do not at‐
297       tempt to install the gems in the excluded groups, and only evaluate  as
298       part of the dependency resolution process.
299
300       This  also means that you cannot include different versions of the same
301       gem in different groups, because doing so  would  result  in  different
302       sets of dependencies used in development and production. Because of the
303       vagaries of the dependency resolution  process,  this  usually  affects
304       more  than the gems you list in your Gemfile(5), and can (surprisingly)
305       radically change the gems you are using.
306

THE GEMFILE.LOCK

308       When you run bundle install, Bundler will persist the  full  names  and
309       versions  of all gems that you used (including dependencies of the gems
310       specified in the Gemfile(5)) into a file called Gemfile.lock.
311
312       Bundler uses this file in all subsequent calls to bundle install, which
313       guarantees that you always use the same exact code, even as your appli‐
314       cation moves across machines.
315
316       Because of the way dependency resolution works, even a seemingly  small
317       change (for instance, an update to a point-release of a dependency of a
318       gem in your Gemfile(5)) can result in radically  different  gems  being
319       needed to satisfy all dependencies.
320
321       As  a  result, you SHOULD check your Gemfile.lock into version control,
322       in both applications and gems. If you do not, every machine that checks
323       out your repository (including your production server) will resolve all
324       dependencies  again,  which  will  result  in  different  versions   of
325       third-party code being used if any of the gems in the Gemfile(5) or any
326       of their dependencies have been updated.
327
328       When Bundler first shipped, the Gemfile.lock was included in the  .git‐
329       ignore file included with generated gems. Over time, however, it became
330       clear that this practice forces the pain of  broken  dependencies  onto
331       new  contributors,  while leaving existing contributors potentially un‐
332       aware of the problem. Since bundle install is usually  the  first  step
333       towards  a contribution, the pain of broken dependencies would discour‐
334       age new contributors from contributing. As a result,  we  have  revised
335       our  guidance for gem authors to now recommend checking in the lock for
336       gems.
337

CONSERVATIVE UPDATING

339       When you make a change to the Gemfile(5) and then run  bundle  install,
340       Bundler will update only the gems that you modified.
341
342       In  other  words,  if  a  gem that you did not modify worked before you
343       called bundle install, it will continue to use the exact same  versions
344       of all dependencies as it used before the update.
345
346       Let´s take a look at an example. Here´s your original Gemfile(5):
347
348
349
350           source ´https://rubygems.org´
351
352           gem ´actionpack´, ´2.3.8´
353           gem ´activemerchant´
354
355
356
357       In  this  case, both actionpack and activemerchant depend on activesup‐
358       port. The actionpack gem depends on activesupport  2.3.8  and  rack  ~>
359       1.1.0,  while the activemerchant gem depends on activesupport >= 2.3.2,
360       braintree >= 2.0.0, and builder >= 2.0.0.
361
362       When the dependencies are  first  resolved,  Bundler  will  select  ac‐
363       tivesupport  2.3.8,  which  satisfies  the requirements of both gems in
364       your Gemfile(5).
365
366       Next, you modify your Gemfile(5) to:
367
368
369
370           source ´https://rubygems.org´
371
372           gem ´actionpack´, ´3.0.0.rc´
373           gem ´activemerchant´
374
375
376
377       The actionpack 3.0.0.rc gem has a number of new dependencies,  and  up‐
378       dates  the  activesupport  dependency to = 3.0.0.rc and the rack depen‐
379       dency to ~> 1.2.1.
380
381       When you run bundle install, Bundler notices that you changed  the  ac‐
382       tionpack  gem,  but  not  the activemerchant gem. It evaluates the gems
383       currently being used to satisfy its requirements:
384
385       activesupport 2.3.8
386              also used to satisfy a dependency in  activemerchant,  which  is
387              not being updated
388
389       rack ~> 1.1.0
390              not currently being used to satisfy another dependency
391
392       Because  you did not explicitly ask to update activemerchant, you would
393       not expect it to suddenly stop working after updating actionpack.  How‐
394       ever,  satisfying  the new activesupport 3.0.0.rc dependency of action‐
395       pack requires updating one of its dependencies.
396
397       Even though activemerchant declares a very loose dependency that  theo‐
398       retically  matches  activesupport 3.0.0.rc, Bundler treats gems in your
399       Gemfile(5) that have not changed as an atomic unit together with  their
400       dependencies. In this case, the activemerchant dependency is treated as
401       activemerchant 1.7.1 + activesupport 2.3.8, so bundle install will  re‐
402       port that it cannot update actionpack.
403
404       To explicitly update actionpack, including its dependencies which other
405       gems in the Gemfile(5) still depend on, run  bundle  update  actionpack
406       (see bundle update(1)).
407
408       Summary:  In  general,  after  making  a change to the Gemfile(5) , you
409       should first try to run bundle install, which will  guarantee  that  no
410       other gem in the Gemfile(5) is impacted by the change. If that does not
411       work, run bundle update(1) bundle-update.1.html.
412

SEE ALSO

414       •   Gem  install  docs  http://guides.rubygems.org/rubygems-basics/#in‐
415           stalling-gems
416
417       •   Rubygems signing docs http://guides.rubygems.org/security/
418
419
420
421
422
423
424                                 January 2021                BUNDLE-INSTALL(1)
Impressum