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

DEPLOYMENT MODE

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

SUDO USAGE

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

INSTALLING GROUPS

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

THE GEMFILE.LOCK

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

CONSERVATIVE UPDATING

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

SEE ALSO

386       ·   Gem                          install                           docs
387           http://guides.rubygems.org/rubygems-basics/#installing-gems
388
389       ·   Rubygems signing docs http://guides.rubygems.org/security/
390
391
392
393
394
395
396                                 December 2018               BUNDLE-INSTALL(1)
Impressum