/flags/bundler/bundle-install-deployment
bundle install --deployment is deprecated: use bundle config set deployment true
- tool
- Bundler
- command
- bundle install
- flag
- --deployment (deprecated); bundle config set --local deployment true
- default
- off (development defaults: lockfile may be updated, gems in the system location)
bundle install --deployment used to switch Bundler to deployment mode: Gemfile.lock must be present and up to date, Bundler refuses to change it, and gems go to vendor/bundle inside the application. Bundler 2 deprecated the flag (it prints a [DEPRECATED] notice suggesting bundle config set --local deployment 'true'), and the Bundler 4 documentation lists no such option for bundle install. The modern way is the deployment setting, which the bundle-config reference defines as "equivalent to setting frozen to true and path to vendor/bundle".
Old and new commands
# Bundler 1.x style (deprecated)
bundle install --deployment --without development test
# Bundler 2.x and 4.x
bundle config set --local deployment true
bundle config set --local without "development test"
bundle install
# Containers and CI: environment variables, no config file
BUNDLE_DEPLOYMENT=1 BUNDLE_WITHOUT="development:test" bundle install--local stores the setting in the application's .bundle/config; omit it to set it for the user, or use the BUNDLE_* environment variables, which are not written anywhere.
What deployment mode changes
| Aspect | Development defaults | deployment = true |
|---|---|---|
| Gemfile.lock | Created or updated as needed | Required, must match the Gemfile, never changed |
| Gem location | System or user gem directory | vendor/bundle (override with path) |
| Gemfile edited without bundle install | Lockfile is updated | Install fails |
| Equivalent settings | - | frozen = true plus path = vendor/bundle |
Use frozen alone (BUNDLE_FROZEN=true) in CI when you only want the "lockfile must not change" guarantee but keep the default gem location, for example to reuse a cached gem directory.
Related settings
withoutandonlychoose groups; see bundle config set without.pathsets where gems go; see bundle config path.jobsandretrycontrol parallel downloads and network retries.
Pitfalls
- Do not turn deployment mode on in a development checkout: every
Gemfileedit then fails until you unset it withbundle config unset deployment. - A lockfile resolved on macOS may lack Linux platforms; a frozen install on the server then fails. Add them with bundle lock --add-platform.
- Old CI scripts keep working with deprecation warnings on Bundler 2 but must be changed before upgrading to Bundler 4.
.bundle/configcommitted by accident carries deployment settings to every developer; keep.bundle/in.gitignore.
FAQ
What does deployment mode do in Bundler?
It is equivalent to setting frozen to true and path to vendor/bundle: Gemfile.lock must exist and be up to date, Bundler may not change it, and gems are installed inside the application instead of the system gem directory.
Why was --deployment deprecated?
Flags such as --deployment, --path and --without were silently remembered in .bundle/config, so one command changed the behaviour of all later ones. Bundler moved these to explicit bundle config settings; Bundler 4 lists no such flags for bundle install any more.
How do I use deployment mode in Docker without a .bundle/config file?
Use the environment variables: ENV BUNDLE_DEPLOYMENT=1 and, if you want another location, BUNDLE_PATH=/usr/local/bundle. They have the same effect as bundle config set and need no file in the image.