1BUNDLE-UPDATE(1) BUNDLE-UPDATE(1)
2
6 bundle-update - Update your gems to the latest available versions
7
9 bundle update *gems [--all] [--group=NAME] [--source=NAME] [--local]
10 [--ruby] [--bundler[=VERSION]] [--full-index] [--jobs=JOBS] [--quiet]
11 [--patch|--minor|--major] [--redownload] [--strict] [--conservative]
12
14 Update the gems specified (all gems, if --all flag is used), ignoring
15 the previously installed gems specified in the Gemfile.lock. In gen‐
16 eral, you should use bundle install(1) bundle-install.1.html to install
17 the same exact gems and versions across machines.
18 You would use bundle update to explicitly update the version of a gem.
20
22 --all Update all gems specified in Gemfile.
23 --group=<name>, -g=[<name>]
25 Only update the gems in the specified group. For instance, you
26 can update all gems in the development group with bundle update
27 --group development. You can also call bundle update rails
28 --group test to update the rails gem and all gems in the test
29 group, for example.
30 --source=<name>
32 The name of a :git or :path source used in the Gemfile(5). For
33 instance, with a :git source of
34 http://github.com/rails/rails.git, you would call bundle update
35 --source rails
36 --local
38 Do not attempt to fetch gems remotely and use the gem cache in‐
39 stead.
40 --ruby Update the locked version of Ruby to the current version of
42 Ruby.
43 --bundler
45 Update the locked version of bundler to the invoked bundler ver‐
46 sion.
47 --full-index
49 Fall back to using the single-file index of all gems.
50 --jobs=[<number>], -j[<number>]
52 Specify the number of jobs to run in parallel. The default is
53 the number of available processors.
54 --retry=[<number>]
56 Retry failed network or git requests for number times.
57 --quiet
59 Only output warnings and errors.
60 --redownload
62 Force downloading every gem.
63 --patch
65 Prefer updating only to next patch version.
66 --minor
68 Prefer updating only to next minor version.
69 --major
71 Prefer updating to next major version (default).
72 --strict
74 Do not allow any gem to be updated past latest --patch | --minor
75 | --major.
76 --conservative
78 Use bundle install conservative update behavior and do not allow
79 indirect dependencies to be updated.
80
82 If you run bundle update --all, bundler will ignore any previously in‐
83 stalled gems and resolve all dependencies again based on the latest
84 versions of all gems available in the sources.
85 Consider the following Gemfile(5):
87 source "https://rubygems.org"
91 gem "rails", "3.0.0.rc"
93 gem "nokogiri"
94 When you run bundle install(1) bundle-install.1.html the first time,
98 bundler will resolve all of the dependencies, all the way down, and in‐
99 stall what you need:
100 Fetching gem metadata from https://rubygems.org/.........
104 Resolving dependencies...
105 Installing builder 2.1.2
106 Installing abstract 1.0.0
107 Installing rack 1.2.8
108 Using bundler 1.7.6
109 Installing rake 10.4.0
110 Installing polyglot 0.3.5
111 Installing mime-types 1.25.1
112 Installing i18n 0.4.2
113 Installing mini_portile 0.6.1
114 Installing tzinfo 0.3.42
115 Installing rack-mount 0.6.14
116 Installing rack-test 0.5.7
117 Installing treetop 1.4.15
118 Installing thor 0.14.6
119 Installing activesupport 3.0.0.rc
120 Installing erubis 2.6.6
121 Installing activemodel 3.0.0.rc
122 Installing arel 0.4.0
123 Installing mail 2.2.20
124 Installing activeresource 3.0.0.rc
125 Installing actionpack 3.0.0.rc
126 Installing activerecord 3.0.0.rc
127 Installing actionmailer 3.0.0.rc
128 Installing railties 3.0.0.rc
129 Installing rails 3.0.0.rc
130 Installing nokogiri 1.6.5
131 Bundle complete! 2 Gemfile dependencies, 26 gems total.
133 Use `bundle show [gemname]` to see where a bundled gem is installed.
134 As you can see, even though you have two gems in the Gemfile(5), your
138 application needs 26 different gems in order to run. Bundler remembers
139 the exact versions it installed in Gemfile.lock. The next time you run
140 bundle install(1) bundle-install.1.html, bundler skips the dependency
141 resolution and installs the same gems as it installed last time.
142 After checking in the Gemfile.lock into version control and cloning it
144 on another machine, running bundle install(1) bundle-install.1.html
145 will still install the gems that you installed last time. You don´t
146 need to worry that a new release of erubis or mail changes the gems you
147 use.
148 However, from time to time, you might want to update the gems you are
150 using to the newest versions that still match the gems in your Gem‐
151 file(5).
152 To do this, run bundle update --all, which will ignore the Gem‐
154 file.lock, and resolve all the dependencies again. Keep in mind that
155 this process can result in a significantly different set of the 25
156 gems, based on the requirements of new gems that the gem authors re‐
157 leased since the last time you ran bundle update --all.
158
160 Sometimes, you want to update a single gem in the Gemfile(5), and leave
161 the rest of the gems that you specified locked to the versions in the
162 Gemfile.lock.
163 For instance, in the scenario above, imagine that nokogiri releases
165 version 1.4.4, and you want to update it without updating Rails and all
166 of its dependencies. To do this, run bundle update nokogiri.
167 Bundler will update nokogiri and any of its dependencies, but leave
169 alone Rails and its dependencies.
170
172 Sometimes, multiple gems declared in your Gemfile(5) are satisfied by
173 the same second-level dependency. For instance, consider the case of
174 thin and rack-perftools-profiler.
175 source "https://rubygems.org"
179 gem "thin"
181 gem "rack-perftools-profiler"
182 The thin gem depends on rack >= 1.0, while rack-perftools-profiler de‐
186 pends on rack ~> 1.0. If you run bundle install, you get:
187 Fetching source index for https://rubygems.org/
191 Installing daemons (1.1.0)
192 Installing eventmachine (0.12.10) with native extensions
193 Installing open4 (1.0.1)
194 Installing perftools.rb (0.4.7) with native extensions
195 Installing rack (1.2.1)
196 Installing rack-perftools_profiler (0.0.2)
197 Installing thin (1.2.7) with native extensions
198 Using bundler (1.0.0.rc.3)
199 In this case, the two gems have their own set of dependencies, but they
203 share rack in common. If you run bundle update thin, bundler will up‐
204 date daemons, eventmachine and rack, which are dependencies of thin,
205 but not open4 or perftools.rb, which are dependencies of
206 rack-perftools_profiler. Note that bundle update thin will update rack
207 even though it´s also a dependency of rack-perftools_profiler.
208 In short, by default, when you update a gem using bundle update,
210 bundler will update all dependencies of that gem, including those that
211 are also dependencies of another gem.
212 To prevent updating indirect dependencies, prior to version 1.14 the
214 only option was the CONSERVATIVE UPDATING behavior in bundle install(1)
215 bundle-install.1.html:
216 In this scenario, updating the thin version manually in the Gemfile(5),
218 and then running bundle install(1) bundle-install.1.html will only up‐
219 date daemons and eventmachine, but not rack. For more information, see
220 the CONSERVATIVE UPDATING section of bundle install(1) bundle-in‐
221 stall.1.html.
222 Starting with 1.14, specifying the --conservative option will also pre‐
224 vent indirect dependencies from being updated.
225
227 Version 1.14 introduced 4 patch-level options that will influence how
228 gem versions are resolved. One of the following options can be used:
229 --patch, --minor or --major. --strict can be added to further influence
230 resolution.
231 --patch
233 Prefer updating only to next patch version.
234 --minor
236 Prefer updating only to next minor version.
237 --major
239 Prefer updating to next major version (default).
240 --strict
242 Do not allow any gem to be updated past latest --patch | --minor
243 | --major.
244 When Bundler is resolving what versions to use to satisfy declared re‐
246 quirements in the Gemfile or in parent gems, it looks up all available
247 versions, filters out any versions that don´t satisfy the requirement,
248 and then, by default, sorts them from newest to oldest, considering
249 them in that order.
250 Providing one of the patch level options (e.g. --patch) changes the
252 sort order of the satisfying versions, causing Bundler to consider the
253 latest --patch or --minor version available before other versions. Note
254 that versions outside the stated patch level could still be resolved to
255 if necessary to find a suitable dependency graph.
256 For example, if gem ´foo´ is locked at 1.0.2, with no gem requirement
258 defined in the Gemfile, and versions 1.0.3, 1.0.4, 1.1.0, 1.1.1, 2.0.0
259 all exist, the default order of preference by default (--major) will be
260 "2.0.0, 1.1.1, 1.1.0, 1.0.4, 1.0.3, 1.0.2".
261 If the --patch option is used, the order of preference will change to
263 "1.0.4, 1.0.3, 1.0.2, 1.1.1, 1.1.0, 2.0.0".
264 If the --minor option is used, the order of preference will change to
266 "1.1.1, 1.1.0, 1.0.4, 1.0.3, 1.0.2, 2.0.0".
267 Combining the --strict option with any of the patch level options will
269 remove any versions beyond the scope of the patch level option, to en‐
270 sure that no gem is updated that far.
271 To continue the previous example, if both --patch and --strict options
273 are used, the available versions for resolution would be "1.0.4, 1.0.3,
274 1.0.2". If --minor and --strict are used, it would be "1.1.1, 1.1.0,
275 1.0.4, 1.0.3, 1.0.2".
276 Gem requirements as defined in the Gemfile will still be the first de‐
278 termining factor for what versions are available. If the gem require‐
279 ment for foo in the Gemfile is ´~> 1.0´, that will accomplish the same
280 thing as providing the --minor and --strict options.
281
283 Given the following gem specifications:
284 foo 1.4.3, requires: ~> bar 2.0
288 foo 1.4.4, requires: ~> bar 2.0
289 foo 1.4.5, requires: ~> bar 2.1
290 foo 1.5.0, requires: ~> bar 2.1
291 foo 1.5.1, requires: ~> bar 3.0
292 bar with versions 2.0.3, 2.0.4, 2.1.0, 2.1.1, 3.0.0
293 Gemfile:
297 gem ´foo´
301 Gemfile.lock:
305 foo (1.4.3)
309 bar (~> 2.0)
310 bar (2.0.3)
311 Cases:
315 # Command Line Result
319 ------------------------------------------------------------
320 1 bundle update --patch ´foo 1.4.5´, ´bar 2.1.1´
321 2 bundle update --patch foo ´foo 1.4.5´, ´bar 2.1.1´
322 3 bundle update --minor ´foo 1.5.1´, ´bar 3.0.0´
323 4 bundle update --minor --strict ´foo 1.5.0´, ´bar 2.1.1´
324 5 bundle update --patch --strict ´foo 1.4.4´, ´bar 2.0.4´
325 In case 1, bar is upgraded to 2.1.1, a minor version increase, because
329 the dependency from foo 1.4.5 required it.
330 In case 2, only foo is requested to be unlocked, but bar is also al‐
332 lowed to move because it´s not a declared dependency in the Gemfile.
333 In case 3, bar goes up a whole major release, because a minor increase
335 is preferred now for foo, and when it goes to 1.5.1, it requires 3.0.0
336 of bar.
337 In case 4, foo is preferred up to a minor version, but 1.5.1 won´t work
339 because the --strict flag removes bar 3.0.0 from consideration since
340 it´s a major increment.
341 In case 5, both foo and bar have any minor or major increments removed
343 from consideration because of the --strict flag, so the most they can
344 move is up to 1.4.4 and 2.0.4.
345
347 In general, when working with an application managed with bundler, you
348 should use the following workflow:
349 • After you create your Gemfile(5) for the first time, run
351 $ bundle install
353 • Check the resulting Gemfile.lock into version control
355 $ git add Gemfile.lock
357 • When checking out this repository on another development machine,
359 run
360 $ bundle install
362 • When checking out this repository on a deployment machine, run
364 $ bundle install --deployment
366 • After changing the Gemfile(5) to reflect a new or update depen‐
368 dency, run
369 $ bundle install
371 • Make sure to check the updated Gemfile.lock into version control
373 $ git add Gemfile.lock
375 • If bundle install(1) bundle-install.1.html reports a conflict, man‐
377 ually update the specific gems that you changed in the Gemfile(5)
378 $ bundle update rails thin
380 • If you want to update all the gems to the latest possible versions
382 that still match the gems listed in the Gemfile(5), run
383 $ bundle update --all
385 February 2023 BUNDLE-UPDATE(1)