1BUNDLE-INSTALL(1) BUNDLE-INSTALL(1)
2
6 bundle-install - Install the dependencies specified in your Gemfile
7
9 bundle install [--gemfile=GEMFILE]
10 [--path PATH] [--system]
14 [--without=GROUP1[ GROUP2...]]
15 [--local] [--deployment]
16 [--binstubs[=DIRECTORY]]
17 [--standalone[=GROUP1[ GROUP2...]]]
18 [--trust-policy=POLICY]
19 [--jobs=SIZE]
20 [--retry=TRIES]
21 [--no-cache]
22 [--quiet]
23 [--clean]
24 [--full-index]
25 [--no-prune]
26 [--shebang]
27
31 Install the gems specified in your Gemfile(5). If this is the first
32 time you run bundle install (and a Gemfile.lock does not exist),
33 bundler will fetch all remote sources, resolve dependencies and install
34 all needed gems.
35 If a Gemfile.lock does exist, and you have not updated your Gemfile(5),
37 bundler will fetch all remote sources, but use the dependencies speci‐
38 fied in the Gemfile.lock instead of resolving dependencies.
39 If a Gemfile.lock does exist, and you have updated your Gemfile(5),
41 bundler will use the dependencies in the Gemfile.lock for all gems that
42 you did not update, but will re-resolve the dependencies of gems that
43 you did update. You can find more information about this update process
44 below under CONSERVATIVE UPDATING.
45
47 --gemfile=<gemfile>
48 The location of the Gemfile(5) that bundler should use. This
49 defaults to a gemfile in the current working directory. In gen‐
50 eral, bundler will assume that the location of the Gemfile(5) is
51 also the project root, and will look for the Gemfile.lock and
52 vendor/cache relative to it.
53 --path=<path>
55 The location to install the gems in the bundle to. This defaults
56 to Rubygems´ gem home, which is also the default location where
57 gem install installs gems. This means that, by default, gems
58 installed without a --path setting will show up in gem list.
59 This setting is a remembered option.
60 --system
62 Installs the gems in the bundle to the system location. This
63 overrides any previous remembered use of --path.
64 --without=<list>
66 A space-separated list of groups to skip installing. This is a
67 remembered option.
68 --local
70 Do not attempt to connect to rubygems.org, instead using just
71 the gems already present in Rubygems´ cache or in vendor/cache.
72 Note that if a more appropriate platform-specific gem exists on
73 rubygems.org, it will not be found.
74 --deployment
76 Switches bundler´s defaults into deployment mode. Do not use
77 this flag on development machines.
78 --binstubs[=<directory>]
80 Create a directory (defaults to bin) containing an executable
81 that runs in the context of the bundle. For instance, if the
82 rails gem comes with a rails executable, this flag will create a
83 bin/rails executable that ensures that all dependencies used
84 come from the bundled gems.
85 --shebang ruby-install-name
87 Uses the ruby executable (usually ruby) provided to execute the
88 scripts created with --binstubs. For instance, if you use --bin‐
89 stubs with --shebang jruby, all executables will be created to
90 use jruby instead.
91 --standalone[=<list>]
93 Make a bundle that can work without Ruby Gems or Bundler at run‐
94 time. It takes a space separated list of groups to install. It
95 creates a bundle directory and installs the bundle there. It
96 also generates a bundle/bundler/setup.rb file to replace
97 Bundler´s own setup.
98 --trust-policy=[<policy>]
100 Apply the Rubygems security policy named policy, where policy is
101 one of HighSecurity, MediumSecurity, LowSecurity, AlmostNoSecu‐
102 rity, or NoSecurity. For more detail, see the Rubygems signing
103 documentation, linked below in SEE ALSO.
104 --jobs=[<size>]
106 Install gems parallely by starting size number of parallel work‐
107 ers.
108 --retry[<tries]
110 Retries failed network or git requests tries times.
111 --no-cache
113 Do not update the cache in vendor/cache with the newly bundled
114 gems. This does not remove any existing cached gems, only stops
115 the newly bundled gems from being cached during the install.
116 --quiet
118 Do not print progress information to stdout. Instead, communi‐
119 cate the success of the install operation via exit status code.
120 --clean
122 Run bundle clean automatically after install.
123 --full-index
125 Use the rubygems modern index instead of the API endpoint.
126 --no-prune
128 Don´t remove stale gems from the cache.
129
131 Bundler´s defaults are optimized for development. To switch to defaults
132 optimized for deployment, use the --deployment flag. Do not activate
133 deployment mode on development machines, as it will cause in an error
134 when the Gemfile is modified.
135 1. A Gemfile.lock is required.
137 To ensure that the same versions of the gems you developed with and
139 tested with are also used in deployments, a Gemfile.lock is
140 required.
141 This is mainly to ensure that you remember to check your Gem‐
143 file.lock into version control.
144 2. The Gemfile.lock must be up to date
146 In development, you can modify your Gemfile(5) and re-run bundle
148 install to conservatively update your Gemfile.lock snapshot.
149 In deployment, your Gemfile.lock should be up-to-date with changes
151 made in your Gemfile(5).
152 3. Gems are installed to vendor/bundle not your default system loca‐
154 tion
155 In development, it´s convenient to share the gems used in your
157 application with other applications and other scripts run on the
158 system.
159 In deployment, isolation is a more important default. In addition,
161 the user deploying the application may not have permission to
162 install gems to the system, or the web server may not have permis‐
163 sion to read them.
164 As a result, bundle install --deployment installs gems to the ven‐
166 dor/bundle directory in the application. This may be overridden
167 using the --path option.
168
172 By default, bundler installs gems to the same location as gem install.
173 In some cases, that location may not be writable by your Unix user. In
175 that case, bundler will stage everything in a temporary directory, then
176 ask you for your sudo password in order to copy the gems into their
177 system location.
178 From your perspective, this is identical to installing them gems
180 directly into the system.
181 You should never use sudo bundle install. This is because several other
183 steps in bundle install must be performed as the current user:
184 · Updating your Gemfile.lock
186 · Updating your vendor/cache, if necessary
188 · Checking out private git repositories using your user´s SSH keys
190 Of these three, the first two could theoretically be performed by
194 chowning the resulting files to $SUDO_USER. The third, however, can
195 only be performed by actually invoking the git command as the current
196 user. Therefore, git gems are downloaded and installed into ~/.bundle
197 rather than $GEM_HOME or $BUNDLE_PATH.
198 As a result, you should run bundle install as the current user, and
200 bundler will ask for your password if it is needed to put the gems into
201 their final location.
202
204 By default, bundle install will install all gems in all groups in your
205 Gemfile(5), except those declared for a different platform.
206 However, you can explicitly tell bundler to skip installing certain
208 groups with the --without option. This option takes a space-separated
209 list of groups.
210 While the --without option will skip installing the gems in the speci‐
212 fied groups, it will still download those gems and use them to resolve
213 the dependencies of every gem in your Gemfile(5).
214 This is so that installing a different set of groups on another machine
216 (such as a production server) will not change the gems and versions
217 that you have already developed and tested against.
218 Bundler offers a rock-solid guarantee that the third-party code you are
220 running in development and testing is also the third-party code you are
221 running in production. You can choose to exclude some of that code in
222 different environments, but you will never be caught flat-footed by
223 different versions of third-party code being used in different environ‐
224 ments.
225 For a simple illustration, consider the following Gemfile(5):
227 source "https://rubygems.org"
231 gem "sinatra"
233 group :production do
235 gem "rack-perftools-profiler"
236 end
237 In this case, sinatra depends on any version of Rack (>= 1.0, while
241 rack-perftools-profiler depends on 1.x (~> 1.0).
242 When you run bundle install --without production in development, we
244 look at the dependencies of rack-perftools-profiler as well. That way,
245 you do not spend all your time developing against Rack 2.0, using new
246 APIs unavailable in Rack 1.x, only to have bundler switch to Rack 1.2
247 when the production group is used.
248 This should not cause any problems in practice, because we do not
250 attempt to install the gems in the excluded groups, and only evaluate
251 as part of the dependency resolution process.
252 This also means that you cannot include different versions of the same
254 gem in different groups, because doing so would result in different
255 sets of dependencies used in development and production. Because of the
256 vagaries of the dependency resolution process, this usually affects
257 more than just the gems you list in your Gemfile(5), and can (surpris‐
258 ingly) radically change the gems you are using.
259
261 Some options (marked above in the OPTIONS section) are remembered
262 between calls to bundle install, and by the Bundler runtime.
263 For instance, if you run bundle install --without test, a subsequent
265 call to bundle install that does not include a --without flag will
266 remember your previous choice.
267 In addition, a call to Bundler.setup will not attempt to make the gems
269 in those groups available on the Ruby load path, as they were not
270 installed.
271 The settings that are remembered are:
273 --deployment
275 At runtime, this remembered setting will also result in Bundler
276 raising an exception if the Gemfile.lock is out of date.
277 --path Subsequent calls to bundle install will install gems to the
279 directory originally passed to --path. The Bundler runtime will
280 look for gems in that location. You can revert this option by
281 running bundle install --system.
282 --binstubs
284 Bundler will update the executables every subsequent call to
285 bundle install.
286 --without
288 As described above, Bundler will skip the gems specified by
289 --without in subsequent calls to bundle install. The Bundler
290 runtime will also not try to make the gems in the skipped groups
291 available.
292
294 When you run bundle install, Bundler will persist the full names and
295 versions of all gems that you used (including dependencies of the gems
296 specified in the Gemfile(5)) into a file called Gemfile.lock.
297 Bundler uses this file in all subsequent calls to bundle install, which
299 guarantees that you always use the same exact code, even as your appli‐
300 cation moves across machines.
301 Because of the way dependency resolution works, even a seemingly small
303 change (for instance, an update to a point-release of a dependency of a
304 gem in your Gemfile(5)) can result in radically different gems being
305 needed to satisfy all dependencies.
306 As a result, you SHOULD check your Gemfile.lock into version control.
308 If you do not, every machine that checks out your repository (including
309 your production server) will resolve all dependencies again, which will
310 result in different versions of third-party code being used if any of
311 the gems in the Gemfile(5) or any of their dependencies have been
312 updated.
313
315 When you make a change to the Gemfile(5) and then run bundle install,
316 Bundler will update only the gems that you modified.
317 In other words, if a gem that you did not modify worked before you
319 called bundle install, it will continue to use the exact same versions
320 of all dependencies as it used before the update.
321 Let´s take a look at an example. Here´s your original Gemfile(5):
323 source "https://rubygems.org"
327 gem "actionpack", "2.3.8"
329 gem "activemerchant"
330 In this case, both actionpack and activemerchant depend on activesup‐
334 port. The actionpack gem depends on activesupport 2.3.8 and rack ~>
335 1.1.0, while the activemerchant gem depends on activesupport >= 2.3.2,
336 braintree >= 2.0.0, and builder >= 2.0.0.
337 When the dependencies are first resolved, Bundler will select
339 activesupport 2.3.8, which satisfies the requirements of both gems in
340 your Gemfile(5).
341 Next, you modify your Gemfile(5) to:
343 source "https://rubygems.org"
347 gem "actionpack", "3.0.0.rc"
349 gem "activemerchant"
350 The actionpack 3.0.0.rc gem has a number of new dependencies, and
354 updates the activesupport dependency to = 3.0.0.rc and the rack depen‐
355 dency to ~> 1.2.1.
356 When you run bundle install, Bundler notices that you changed the
358 actionpack gem, but not the activemerchant gem. It evaluates the gems
359 currently being used to satisfy its requirements:
360 activesupport 2.3.8
362 also used to satisfy a dependency in activemerchant, which is
363 not being updated
364 rack ~> 1.1.0
366 not currently being used to satisfy another dependency
367 Because you did not explicitly ask to update activemerchant, you would
369 not expect it to suddenly stop working after updating actionpack. How‐
370 ever, satisfying the new activesupport 3.0.0.rc dependency of action‐
371 pack requires updating one of its dependencies.
372 Even though activemerchant declares a very loose dependency that theo‐
374 retically matches activesupport 3.0.0.rc, bundler treats gems in your
375 Gemfile(5) that have not changed as an atomic unit together with their
376 dependencies. In this case, the activemerchant dependency is treated as
377 activemerchant 1.7.1 + activesupport 2.3.8, so bundle install will
378 report that it cannot update actionpack.
379 To explicitly update actionpack, including its dependencies which other
381 gems in the Gemfile(5) still depend on, run bundle update actionpack
382 (see bundle update(1)).
383 Summary: In general, after making a change to the Gemfile(5) , you
385 should first try to run bundle install, which will guarantee that no
386 other gems in the Gemfile(5) are impacted by the change. If that does
387 not work, run bundle update(1) bundle-update.1.html.
388
390 · Gem install docs:
391 http://guides.rubygems.org/rubygems-basics/#installing-gems
392 · Rubygems signing docs: http://guides.rubygems.org/security/
394 December 2014 BUNDLE-INSTALL(1)