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

DEPLOYMENT MODE

155       Bundler´s defaults are optimized for development. To switch to defaults
156       optimized  for deployment and for CI, use the --deployment flag. Do not
157       activate deployment mode on development machines, as it will  cause  an
158       error when the Gemfile(5) is modified.
159
160       1.  A Gemfile.lock is required.
161
162           To ensure that the same versions of the gems you developed with and
163           tested with  are  also  used  in  deployments,  a  Gemfile.lock  is
164           required.
165
166           This  is  mainly  to  ensure  that  you remember to check your Gem‐
167           file.lock into version control.
168
169       2.  The Gemfile.lock must be up to date
170
171           In development, you can modify your Gemfile(5)  and  re-run  bundle
172           install to conservatively update your Gemfile.lock snapshot.
173
174           In  deployment, your Gemfile.lock should be up-to-date with changes
175           made in your Gemfile(5).
176
177       3.  Gems are installed to vendor/bundle not your default  system  loca‐
178           tion
179
180           In  development,  it´s  convenient  to  share the gems used in your
181           application with other applications and other scripts that  run  on
182           the system.
183
184           In  deployment, isolation is a more important default. In addition,
185           the user deploying the  application  may  not  have  permission  to
186           install  gems to the system, or the web server may not have permis‐
187           sion to read them.
188
189           As a result, bundle install --deployment installs gems to the  ven‐
190           dor/bundle  directory  in  the  application. This may be overridden
191           using the --path option.
192
193
194

SUDO USAGE

196       By default, Bundler installs gems to the same location as gem install.
197
198       In some cases, that location may not be writable by your Unix user.  In
199       that case, Bundler will stage everything in a temporary directory, then
200       ask you for your sudo password in order to copy  the  gems  into  their
201       system location.
202
203       From  your  perspective,  this  is  identical  to  installing  the gems
204       directly into the system.
205
206       You should never use sudo bundle install. This is because several other
207       steps in bundle install must be performed as the current user:
208
209       ·   Updating your Gemfile.lock
210
211       ·   Updating your vendor/cache, if necessary
212
213       ·   Checking out private git repositories using your user´s SSH keys
214
215
216
217       Of  these  three,  the  first  two  could theoretically be performed by
218       chowning the resulting files to $SUDO_USER.  The  third,  however,  can
219       only  be  performed  by  invoking  the git command as the current user.
220       Therefore, git gems are downloaded and installed into ~/.bundle  rather
221       than $GEM_HOME or $BUNDLE_PATH.
222
223       As  a  result,  you  should run bundle install as the current user, and
224       Bundler will ask for your password if it is needed to put the gems into
225       their final location.
226

INSTALLING GROUPS

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

THE GEMFILE.LOCK

285       When  you  run  bundle install, Bundler will persist the full names and
286       versions of all gems that you used (including dependencies of the  gems
287       specified in the Gemfile(5)) into a file called Gemfile.lock.
288
289       Bundler uses this file in all subsequent calls to bundle install, which
290       guarantees that you always use the same exact code, even as your appli‐
291       cation moves across machines.
292
293       Because  of the way dependency resolution works, even a seemingly small
294       change (for instance, an update to a point-release of a dependency of a
295       gem  in  your  Gemfile(5)) can result in radically different gems being
296       needed to satisfy all dependencies.
297
298       As a result, you SHOULD check your Gemfile.lock into  version  control,
299       in both applications and gems. If you do not, every machine that checks
300       out your repository (including your production server) will resolve all
301       dependencies   again,  which  will  result  in  different  versions  of
302       third-party code being used if any of the gems in the Gemfile(5) or any
303       of their dependencies have been updated.
304
305       When  Bundler first shipped, the Gemfile.lock was included in the .git‐
306       ignore file included with generated gems. Over time, however, it became
307       clear  that  this  practice forces the pain of broken dependencies onto
308       new  contributors,  while  leaving  existing  contributors  potentially
309       unaware  of the problem. Since bundle install is usually the first step
310       towards a contribution, the pain of broken dependencies would  discour‐
311       age  new  contributors  from contributing. As a result, we have revised
312       our guidance for gem authors to now recommend checking in the lock  for
313       gems.
314

CONSERVATIVE UPDATING

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

SEE ALSO

391       ·   Gem                           install                          docs
392           http://guides.rubygems.org/rubygems-basics/#installing-gems
393
394       ·   Rubygems signing docs http://guides.rubygems.org/security/
395
396
397
398
399
400
401                                 January 2020                BUNDLE-INSTALL(1)
Impressum