1BUNDLE-UPDATE(1) BUNDLE-UPDATE(1)
2
6 bundle-update - Update your gems to the latest available versions
7
9 bundle update *gems [--group=NAME] [--source=NAME] [--local] [--ruby]
10 [--bundler[=VERSION]] [--full-index] [--jobs=JOBS] [--quiet] [--force]
11 [--patch|--minor|--major] [--strict] [--conservative]
12
14 Update the gems specified (all gems, if none are specified), ignoring
15 the previously installed gems specified in the Gemfile.lock. In gen‐
16 eral, you should use [bundle install(1)][bundle-install] to install the
17 same exact gems and versions across machines.
18 You would use bundle update to explicitly update the version of a gem.
20
22 --group=<name>, -g=[<name>]
23 Only update the gems in the specified group. For instance, you
24 can update all gems in the development group with bundle update
25 --group development. You can also call bundle update rails
26 --group test to update the rails gem and all gems in the test
27 group, for example.
28 --source=<name>
30 The name of a :git or :path source used in the Gemfile(5). For
31 instance, with a :git source of
32 http://github.com/rails/rails.git, you would call bundle update
33 --source rails
34 --local
36 Do not attempt to fetch gems remotely and use the gem cache
37 instead.
38 --ruby Update the locked version of Ruby to the current version of
40 Ruby.
41 --bundler
43 Update the locked version of bundler to the invoked bundler ver‐
44 sion.
45 --full-index
47 Fall back to using the single-file index of all gems.
48 --jobs=[<number>], -j[<number>]
50 Specify the number of jobs to run in parallel. The default is 1.
51 --retry=[<number>]
53 Retry failed network or git requests for number times.
54 --quiet
56 Only output warnings and errors.
57 --force
59 Force downloading every gem.
60 --patch
62 Prefer updating only to next patch version.
63 --minor
65 Prefer updating only to next minor version.
66 --major
68 Prefer updating to next major version (default).
69 --strict
71 Do not allow any gem to be updated past latest --patch | --minor
72 | --major.
73 --conservative
75 Use bundle install conservative update behavior and do not allow
76 shared dependencies to be updated.
77
79 If you run bundle update with no parameters, bundler will ignore any
80 previously installed gems and resolve all dependencies again based on
81 the latest versions of all gems available in the sources.
82 Consider the following Gemfile(5):
84 source "https://rubygems.org"
88 gem "rails", "3.0.0.rc"
90 gem "nokogiri"
91 When you run [bundle install(1)][bundle-install] the first time,
95 bundler will resolve all of the dependencies, all the way down, and
96 install what you need:
97 Fetching gem metadata from https://rubygems.org/.........
101 Resolving dependencies...
102 Installing builder 2.1.2
103 Installing abstract 1.0.0
104 Installing rack 1.2.8
105 Using bundler 1.7.6
106 Installing rake 10.4.0
107 Installing polyglot 0.3.5
108 Installing mime-types 1.25.1
109 Installing i18n 0.4.2
110 Installing mini_portile 0.6.1
111 Installing tzinfo 0.3.42
112 Installing rack-mount 0.6.14
113 Installing rack-test 0.5.7
114 Installing treetop 1.4.15
115 Installing thor 0.14.6
116 Installing activesupport 3.0.0.rc
117 Installing erubis 2.6.6
118 Installing activemodel 3.0.0.rc
119 Installing arel 0.4.0
120 Installing mail 2.2.20
121 Installing activeresource 3.0.0.rc
122 Installing actionpack 3.0.0.rc
123 Installing activerecord 3.0.0.rc
124 Installing actionmailer 3.0.0.rc
125 Installing railties 3.0.0.rc
126 Installing rails 3.0.0.rc
127 Installing nokogiri 1.6.5
128 Bundle complete! 2 Gemfile dependencies, 26 gems total.
130 Use `bundle show [gemname]` to see where a bundled gem is installed.
131 As you can see, even though you have two gems in the Gemfile(5), your
135 application needs 26 different gems in order to run. Bundler remembers
136 the exact versions it installed in Gemfile.lock. The next time you run
137 [bundle install(1)][bundle-install], bundler skips the dependency reso‐
138 lution and installs the same gems as it installed last time.
139 After checking in the Gemfile.lock into version control and cloning it
141 on another machine, running [bundle install(1)][bundle-install] will
142 still install the gems that you installed last time. You don´t need to
143 worry that a new release of erubis or mail changes the gems you use.
144 However, from time to time, you might want to update the gems you are
146 using to the newest versions that still match the gems in your Gem‐
147 file(5).
148 To do this, run bundle update, which will ignore the Gemfile.lock, and
150 resolve all the dependencies again. Keep in mind that this process can
151 result in a significantly different set of the 25 gems, based on the
152 requirements of new gems that the gem authors released since the last
153 time you ran bundle update.
154
156 Sometimes, you want to update a single gem in the Gemfile(5), and leave
157 the rest of the gems that you specified locked to the versions in the
158 Gemfile.lock.
159 For instance, in the scenario above, imagine that nokogiri releases
161 version 1.4.4, and you want to update it without updating Rails and all
162 of its dependencies. To do this, run bundle update nokogiri.
163 Bundler will update nokogiri and any of its dependencies, but leave
165 alone Rails and its dependencies.
166
168 Sometimes, multiple gems declared in your Gemfile(5) are satisfied by
169 the same second-level dependency. For instance, consider the case of
170 thin and rack-perftools-profiler.
171 source "https://rubygems.org"
175 gem "thin"
177 gem "rack-perftools-profiler"
178 The thin gem depends on rack >= 1.0, while rack-perftools-profiler
182 depends on rack ~> 1.0. If you run bundle install, you get:
183 Fetching source index for https://rubygems.org/
187 Installing daemons (1.1.0)
188 Installing eventmachine (0.12.10) with native extensions
189 Installing open4 (1.0.1)
190 Installing perftools.rb (0.4.7) with native extensions
191 Installing rack (1.2.1)
192 Installing rack-perftools_profiler (0.0.2)
193 Installing thin (1.2.7) with native extensions
194 Using bundler (1.0.0.rc.3)
195 In this case, the two gems have their own set of dependencies, but they
199 share rack in common. If you run bundle update thin, bundler will
200 update daemons, eventmachine and rack, which are dependencies of thin,
201 but not open4 or perftools.rb, which are dependencies of
202 rack-perftools_profiler. Note that bundle update thin will update rack
203 even though it´s also a dependency of rack-perftools_profiler.
204 In short, by default, when you update a gem using bundle update,
206 bundler will update all dependencies of that gem, including those that
207 are also dependencies of another gem.
208 To prevent updating shared dependencies, prior to version 1.14 the only
210 option was the CONSERVATIVE UPDATING behavior in [bundle
211 install(1)][bundle-install]:
212 In this scenario, updating the thin version manually in the Gemfile(5),
214 and then running [bundle install(1)][bundle-install] will only update
215 daemons and eventmachine, but not rack. For more information, see the
216 CONSERVATIVE UPDATING section of [bundle install(1)][bundle-install].
217 Starting with 1.14, specifying the --conservative option will also pre‐
219 vent shared dependencies from being updated.
220
222 Version 1.14 introduced 4 patch-level options that will influence how
223 gem versions are resolved. One of the following options can be used:
224 --patch, --minor or --major. --strict can be added to further influence
225 resolution.
226 --patch
228 Prefer updating only to next patch version.
229 --minor
231 Prefer updating only to next minor version.
232 --major
234 Prefer updating to next major version (default).
235 --strict
237 Do not allow any gem to be updated past latest --patch | --minor
238 | --major.
239 When Bundler is resolving what versions to use to satisfy declared
241 requirements in the Gemfile or in parent gems, it looks up all avail‐
242 able versions, filters out any versions that don´t satisfy the require‐
243 ment, and then, by default, sorts them from newest to oldest, consider‐
244 ing them in that order.
245 Providing one of the patch level options (e.g. --patch) changes the
247 sort order of the satisfying versions, causing Bundler to consider the
248 latest --patch or --minor version available before other versions. Note
249 that versions outside the stated patch level could still be resolved to
250 if necessary to find a suitable dependency graph.
251 For example, if gem ´foo´ is locked at 1.0.2, with no gem requirement
253 defined in the Gemfile, and versions 1.0.3, 1.0.4, 1.1.0, 1.1.1, 2.0.0
254 all exist, the default order of preference by default (--major) will be
255 "2.0.0, 1.1.1, 1.1.0, 1.0.4, 1.0.3, 1.0.2".
256 If the --patch option is used, the order of preference will change to
258 "1.0.4, 1.0.3, 1.0.2, 1.1.1, 1.1.0, 2.0.0".
259 If the --minor option is used, the order of preference will change to
261 "1.1.1, 1.1.0, 1.0.4, 1.0.3, 1.0.2, 2.0.0".
262 Combining the --strict option with any of the patch level options will
264 remove any versions beyond the scope of the patch level option, to
265 ensure that no gem is updated that far.
266 To continue the previous example, if both --patch and --strict options
268 are used, the available versions for resolution would be "1.0.4, 1.0.3,
269 1.0.2". If --minor and --strict are used, it would be "1.1.1, 1.1.0,
270 1.0.4, 1.0.3, 1.0.2".
271 Gem requirements as defined in the Gemfile will still be the first
273 determining factor for what versions are available. If the gem require‐
274 ment for foo in the Gemfile is ´~> 1.0´, that will accomplish the same
275 thing as providing the --minor and --strict options.
276
278 Given the following gem specifications:
279 foo 1.4.3, requires: ~> bar 2.0
283 foo 1.4.4, requires: ~> bar 2.0
284 foo 1.4.5, requires: ~> bar 2.1
285 foo 1.5.0, requires: ~> bar 2.1
286 foo 1.5.1, requires: ~> bar 3.0
287 bar with versions 2.0.3, 2.0.4, 2.1.0, 2.1.1, 3.0.0
288 Gemfile:
292 gem ´foo´
296 Gemfile.lock:
300 foo (1.4.3)
304 bar (~> 2.0)
305 bar (2.0.3)
306 Cases:
310 # Command Line Result
314 ------------------------------------------------------------
315 1 bundle update --patch ´foo 1.4.5´, ´bar 2.1.1´
316 2 bundle update --patch foo ´foo 1.4.5´, ´bar 2.1.1´
317 3 bundle update --minor ´foo 1.5.1´, ´bar 3.0.0´
318 4 bundle update --minor --strict ´foo 1.5.0´, ´bar 2.1.1´
319 5 bundle update --patch --strict ´foo 1.4.4´, ´bar 2.0.4´
320 In case 1, bar is upgraded to 2.1.1, a minor version increase, because
324 the dependency from foo 1.4.5 required it.
325 In case 2, only foo is requested to be unlocked, but bar is also
327 allowed to move because it´s not a declared dependency in the Gemfile.
328 In case 3, bar goes up a whole major release, because a minor increase
330 is preferred now for foo, and when it goes to 1.5.1, it requires 3.0.0
331 of bar.
332 In case 4, foo is preferred up to a minor version, but 1.5.1 won´t work
334 because the --strict flag removes bar 3.0.0 from consideration since
335 it´s a major increment.
336 In case 5, both foo and bar have any minor or major increments removed
338 from consideration because of the --strict flag, so the most they can
339 move is up to 1.4.4 and 2.0.4.
340
342 In general, when working with an application managed with bundler, you
343 should use the following workflow:
344 · After you create your Gemfile(5) for the first time, run
346 $ bundle install
348 · Check the resulting Gemfile.lock into version control
350 $ git add Gemfile.lock
352 · When checking out this repository on another development machine,
354 run
355 $ bundle install
357 · When checking out this repository on a deployment machine, run
359 $ bundle install --deployment
361 · After changing the Gemfile(5) to reflect a new or update depen‐
363 dency, run
364 $ bundle install
366 · Make sure to check the updated Gemfile.lock into version control
368 $ git add Gemfile.lock
370 · If [bundle install(1)][bundle-install] reports a conflict, manually
372 update the specific gems that you changed in the Gemfile(5)
373 $ bundle update rails thin
375 · If you want to update all the gems to the latest possible versions
377 that still match the gems listed in the Gemfile(5), run
378 $ bundle update
380 July 2017 BUNDLE-UPDATE(1)