/flags/bundler/bundle-install-jobs
bundle install --jobs 4 (-j): install gems in parallel
- tool
- Bundler
- command
- bundle install
- flag
- -j, --jobs NUMBER
- default
- the number of available processors
bundle install --jobs 4 (short -j4) lets Bundler download and install up to four gems at the same time. Large Rails applications with many gems, especially gems with native extensions, install noticeably faster in parallel. Current Bundler already defaults to the number of available processors, so the option matters mainly to limit parallelism on small CI machines, to raise it where downloads dominate, or on older Bundler releases that installed gems one by one by default.
Usage
bundle install --jobs 4 # up to 4 gems in parallel
bundle install -j1 # sequential, easier to read logs when debugging
bundle config set --global jobs 4 # remember it for this user
BUNDLE_JOBS=4 bundle install # environment form, common in Docker and CIRelated options and settings
| Option or setting | Effect |
|---|---|
| -j, --jobs NUMBER | Parallel download and install jobs for this command |
| jobs (BUNDLE_JOBS) | Same, as a stored setting or environment variable |
| --retry NUMBER / retry (BUNDLE_RETRY) | Retries for failed network requests (default 3) |
| --local | Do not contact rubygems.org; use cached gems only |
| --prefer-local | Prefer installed gems over fetching newer ones |
| --quiet | Only print errors and warnings |
Choosing a number
- Developer machines: the default (number of processors) is fine.
- CI runners with 2 vCPUs and little memory:
--jobs 2or--jobs 3; compiling several native gems at once can exhaust memory and fail with an out-of-memory kill that looks like a random compiler crash. - Download-bound installs (many small pure-Ruby gems, slow network): a value above the CPU count can help, because jobs mostly wait for the network.
Docker example
FROM ruby:3.3-slim
RUN apt-get update && apt-get install -y build-essential
WORKDIR /app
ENV BUNDLE_DEPLOYMENT=1 BUNDLE_WITHOUT="development:test" BUNDLE_JOBS=4
COPY Gemfile Gemfile.lock ./
RUN bundle install
COPY . .BUNDLE_DEPLOYMENT and BUNDLE_WITHOUT are explained in bundle install --deployment and bundle config set without.
Pitfalls
- With parallel jobs, log lines of different gems interleave. When a native extension fails, rerun with
-j1to get a readable log of that gem. - Gems that depend on each other at install time are still installed in a valid order; parallelism does not break dependencies.
--jobsdoes not change which versions are installed; that is decided byGemfile.lock.
FAQ
What is the default number of jobs in Bundler?
The current reference says the default is the number of available processors, so bundle install already works in parallel on multi-core machines. Some older Bundler releases installed one gem at a time unless --jobs or the jobs setting was given.
How do I set the number of jobs permanently?
Run bundle config set --global jobs 4, or set BUNDLE_JOBS=4 in the environment. The command-line option overrides both for a single install.
Does --jobs speed up compiling a single native gem?
No. Jobs are parallel per gem: several gems download and install at once. A single gem with a C extension still compiles in one process; for make-level parallelism set MAKEFLAGS=-j4.