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 1.
53 --retry=[<number>]
55 Retry failed network or git requests for number times.
56 --quiet
58 Only output warnings and errors.
59 --redownload
61 Force downloading every gem.
62 --patch
64 Prefer updating only to next patch version.
65 --minor
67 Prefer updating only to next minor version.
68 --major
70 Prefer updating to next major version (default).
71 --strict
73 Do not allow any gem to be updated past latest --patch | --minor
74 | --major.
75 --conservative
77 Use bundle install conservative update behavior and do not allow
78 shared dependencies to be updated.
79
81 If you run bundle update --all, bundler will ignore any previously in‐
82 stalled gems and resolve all dependencies again based on the latest
83 versions of all gems available in the sources.
84 Consider the following Gemfile(5):
86 source "https://rubygems.org"
90 gem "rails", "3.0.0.rc"
92 gem "nokogiri"
93 When you run bundle install(1) bundle-install.1.html the first time,
97 bundler will resolve all of the dependencies, all the way down, and in‐
98 stall what you need:
99 Fetching gem metadata from https://rubygems.org/.........
103 Resolving dependencies...
104 Installing builder 2.1.2
105 Installing abstract 1.0.0
106 Installing rack 1.2.8
107 Using bundler 1.7.6
108 Installing rake 10.4.0
109 Installing polyglot 0.3.5
110 Installing mime-types 1.25.1
111 Installing i18n 0.4.2
112 Installing mini_portile 0.6.1
113 Installing tzinfo 0.3.42
114 Installing rack-mount 0.6.14
115 Installing rack-test 0.5.7
116 Installing treetop 1.4.15
117 Installing thor 0.14.6
118 Installing activesupport 3.0.0.rc
119 Installing erubis 2.6.6
120 Installing activemodel 3.0.0.rc
121 Installing arel 0.4.0
122 Installing mail 2.2.20
123 Installing activeresource 3.0.0.rc
124 Installing actionpack 3.0.0.rc
125 Installing activerecord 3.0.0.rc
126 Installing actionmailer 3.0.0.rc
127 Installing railties 3.0.0.rc
128 Installing rails 3.0.0.rc
129 Installing nokogiri 1.6.5
130 Bundle complete! 2 Gemfile dependencies, 26 gems total.
132 Use `bundle show [gemname]` to see where a bundled gem is installed.
133 As you can see, even though you have two gems in the Gemfile(5), your
137 application needs 26 different gems in order to run. Bundler remembers
138 the exact versions it installed in Gemfile.lock. The next time you run
139 bundle install(1) bundle-install.1.html, bundler skips the dependency
140 resolution and installs the same gems as it installed last time.
141 After checking in the Gemfile.lock into version control and cloning it
143 on another machine, running bundle install(1) bundle-install.1.html
144 will still install the gems that you installed last time. You don´t
145 need to worry that a new release of erubis or mail changes the gems you
146 use.
147 However, from time to time, you might want to update the gems you are
149 using to the newest versions that still match the gems in your Gem‐
150 file(5).
151 To do this, run bundle update --all, which will ignore the Gem‐
153 file.lock, and resolve all the dependencies again. Keep in mind that
154 this process can result in a significantly different set of the 25
155 gems, based on the requirements of new gems that the gem authors re‐
156 leased since the last time you ran bundle update --all.
157
159 Sometimes, you want to update a single gem in the Gemfile(5), and leave
160 the rest of the gems that you specified locked to the versions in the
161 Gemfile.lock.
162 For instance, in the scenario above, imagine that nokogiri releases
164 version 1.4.4, and you want to update it without updating Rails and all
165 of its dependencies. To do this, run bundle update nokogiri.
166 Bundler will update nokogiri and any of its dependencies, but leave
168 alone Rails and its dependencies.
169
171 Sometimes, multiple gems declared in your Gemfile(5) are satisfied by
172 the same second-level dependency. For instance, consider the case of
173 thin and rack-perftools-profiler.
174 source "https://rubygems.org"
178 gem "thin"
180 gem "rack-perftools-profiler"
181 The thin gem depends on rack >= 1.0, while rack-perftools-profiler de‐
185 pends on rack ~> 1.0. If you run bundle install, you get:
186 Fetching source index for https://rubygems.org/
190 Installing daemons (1.1.0)
191 Installing eventmachine (0.12.10) with native extensions
192 Installing open4 (1.0.1)
193 Installing perftools.rb (0.4.7) with native extensions
194 Installing rack (1.2.1)
195 Installing rack-perftools_profiler (0.0.2)
196 Installing thin (1.2.7) with native extensions
197 Using bundler (1.0.0.rc.3)
198 In this case, the two gems have their own set of dependencies, but they
202 share rack in common. If you run bundle update thin, bundler will up‐
203 date daemons, eventmachine and rack, which are dependencies of thin,
204 but not open4 or perftools.rb, which are dependencies of
205 rack-perftools_profiler. Note that bundle update thin will update rack
206 even though it´s also a dependency of rack-perftools_profiler.
207 In short, by default, when you update a gem using bundle update,
209 bundler will update all dependencies of that gem, including those that
210 are also dependencies of another gem.
211 To prevent updating shared dependencies, prior to version 1.14 the only
213 option was the CONSERVATIVE UPDATING behavior in bundle install(1) bun‐
214 dle-install.1.html:
215 In this scenario, updating the thin version manually in the Gemfile(5),
217 and then running bundle install(1) bundle-install.1.html will only up‐
218 date daemons and eventmachine, but not rack. For more information, see
219 the CONSERVATIVE UPDATING section of bundle install(1) bundle-in‐
220 stall.1.html.
221 Starting with 1.14, specifying the --conservative option will also pre‐
223 vent shared dependencies from being updated.
224
226 Version 1.14 introduced 4 patch-level options that will influence how
227 gem versions are resolved. One of the following options can be used:
228 --patch, --minor or --major. --strict can be added to further influence
229 resolution.
230 --patch
232 Prefer updating only to next patch version.
233 --minor
235 Prefer updating only to next minor version.
236 --major
238 Prefer updating to next major version (default).
239 --strict
241 Do not allow any gem to be updated past latest --patch | --minor
242 | --major.
243 When Bundler is resolving what versions to use to satisfy declared re‐
245 quirements in the Gemfile or in parent gems, it looks up all available
246 versions, filters out any versions that don´t satisfy the requirement,
247 and then, by default, sorts them from newest to oldest, considering
248 them in that order.
249 Providing one of the patch level options (e.g. --patch) changes the
251 sort order of the satisfying versions, causing Bundler to consider the
252 latest --patch or --minor version available before other versions. Note
253 that versions outside the stated patch level could still be resolved to
254 if necessary to find a suitable dependency graph.
255 For example, if gem ´foo´ is locked at 1.0.2, with no gem requirement
257 defined in the Gemfile, and versions 1.0.3, 1.0.4, 1.1.0, 1.1.1, 2.0.0
258 all exist, the default order of preference by default (--major) will be
259 "2.0.0, 1.1.1, 1.1.0, 1.0.4, 1.0.3, 1.0.2".
260 If the --patch option is used, the order of preference will change to
262 "1.0.4, 1.0.3, 1.0.2, 1.1.1, 1.1.0, 2.0.0".
263 If the --minor option is used, the order of preference will change to
265 "1.1.1, 1.1.0, 1.0.4, 1.0.3, 1.0.2, 2.0.0".
266 Combining the --strict option with any of the patch level options will
268 remove any versions beyond the scope of the patch level option, to en‐
269 sure that no gem is updated that far.
270 To continue the previous example, if both --patch and --strict options
272 are used, the available versions for resolution would be "1.0.4, 1.0.3,
273 1.0.2". If --minor and --strict are used, it would be "1.1.1, 1.1.0,
274 1.0.4, 1.0.3, 1.0.2".
275 Gem requirements as defined in the Gemfile will still be the first de‐
277 termining factor for what versions are available. If the gem require‐
278 ment for foo in the Gemfile is ´~> 1.0´, that will accomplish the same
279 thing as providing the --minor and --strict options.
280
282 Given the following gem specifications:
283 foo 1.4.3, requires: ~> bar 2.0
287 foo 1.4.4, requires: ~> bar 2.0
288 foo 1.4.5, requires: ~> bar 2.1
289 foo 1.5.0, requires: ~> bar 2.1
290 foo 1.5.1, requires: ~> bar 3.0
291 bar with versions 2.0.3, 2.0.4, 2.1.0, 2.1.1, 3.0.0
292 Gemfile:
296 gem ´foo´
300 Gemfile.lock:
304 foo (1.4.3)
308 bar (~> 2.0)
309 bar (2.0.3)
310 Cases:
314 # Command Line Result
318 ------------------------------------------------------------
319 1 bundle update --patch ´foo 1.4.5´, ´bar 2.1.1´
320 2 bundle update --patch foo ´foo 1.4.5´, ´bar 2.1.1´
321 3 bundle update --minor ´foo 1.5.1´, ´bar 3.0.0´
322 4 bundle update --minor --strict ´foo 1.5.0´, ´bar 2.1.1´
323 5 bundle update --patch --strict ´foo 1.4.4´, ´bar 2.0.4´
324 In case 1, bar is upgraded to 2.1.1, a minor version increase, because
328 the dependency from foo 1.4.5 required it.
329 In case 2, only foo is requested to be unlocked, but bar is also al‐
331 lowed to move because it´s not a declared dependency in the Gemfile.
332 In case 3, bar goes up a whole major release, because a minor increase
334 is preferred now for foo, and when it goes to 1.5.1, it requires 3.0.0
335 of bar.
336 In case 4, foo is preferred up to a minor version, but 1.5.1 won´t work
338 because the --strict flag removes bar 3.0.0 from consideration since
339 it´s a major increment.
340 In case 5, both foo and bar have any minor or major increments removed
342 from consideration because of the --strict flag, so the most they can
343 move is up to 1.4.4 and 2.0.4.
344
346 In general, when working with an application managed with bundler, you
347 should use the following workflow:
348 • After you create your Gemfile(5) for the first time, run
350 $ bundle install
352 • Check the resulting Gemfile.lock into version control
354 $ git add Gemfile.lock
356 • When checking out this repository on another development machine,
358 run
359 $ bundle install
361 • When checking out this repository on a deployment machine, run
363 $ bundle install --deployment
365 • After changing the Gemfile(5) to reflect a new or update depen‐
367 dency, run
368 $ bundle install
370 • Make sure to check the updated Gemfile.lock into version control
372 $ git add Gemfile.lock
374 • If bundle install(1) bundle-install.1.html reports a conflict, man‐
376 ually update the specific gems that you changed in the Gemfile(5)
377 $ bundle update rails thin
379 • If you want to update all the gems to the latest possible versions
381 that still match the gems listed in the Gemfile(5), run
382 $ bundle update --all
384 January 2021 BUNDLE-UPDATE(1)