Bootsnap

Bootsnap is a library that plugs into Ruby, with optional support for YAML and JSON, to optimize and cache expensive computations. See How Does This Work.

Performance

• Discourse reports a boot time reduction of approximately 50%, from roughly 6 to 3 seconds on one machine;
• One of our smaller internal apps also sees a reduction of 50%, from 3.6 to 1.8 seconds;
• The core Shopify platform -- a rather large monolithic application -- boots about 75% faster, dropping from around 25s to 6.5s.

• In Shopify core (a large app), about 25% of this gain can be attributed to compile_cache_* features; 75% to path caching. This is fairly representative.

Usage

This gem works on macOS and Linux.

Add bootsnap to your Gemfile:

gem 'bootsnap', require: false

If you are using Rails, add this to config/boot.rb immediately after require 'bundler/setup':

require 'bootsnap/setup'

Note that bootsnap writes to tmp/cache (or the path specified by ENV['BOOTSNAP_CACHE_DIR']), and that directory must be writable. Rails will fail to boot if it is not. If this is unacceptable (e.g. you are running in a read-only container and unwilling to mount in a writable tmpdir), you should remove this line or wrap it in a conditional.

Note also that bootsnap will never clean up its own cache: this is left up to you. Depending on your deployment strategy, you may need to periodically purge tmp/cache/bootsnap*. If you notice deploys getting progressively slower, this is almost certainly the cause.

It's technically possible to simply specify gem 'bootsnap', require: 'bootsnap/setup', but it's important to load Bootsnap as early as possible to get maximum performance improvement.

You can see how this require works here.

If you are not using Rails, or if you are but want more control over things, add this to your application setup immediately after require 'bundler/setup' (i.e. as early as possible: the sooner this is loaded, the sooner it can start optimizing things)

require 'bootsnap'
env = ENV['RAILS_ENV'] || "development"
Bootsnap.setup(
  cache_dir:            'tmp/cache',          # Path to your cache
  ignore_directories:   ['node_modules'],     # Directory names to skip.
  development_mode:     env == 'development', # Current working environment, e.g. RACK_ENV, RAILS_ENV, etc
  load_path_cache:      true,                 # Optimize the LOAD_PATH with a cache
  compile_cache_iseq:   true,                 # Compile Ruby code into ISeq cache, breaks coverage reporting.
  compile_cache_yaml:   true,                 # Compile YAML into a cache
  readonly:             true,                 # Use the caches but don't update them on miss or stale entries.
)

Protip: You can replace require 'bootsnap' with BootLib::Require.from_gem('bootsnap', 'bootsnap') using this trick. This will help optimize boot time further if you have an extremely large $LOAD_PATH.

Note: Bootsnap and Spring are orthogonal tools. While Bootsnap speeds up the loading of individual source files, Spring keeps a copy of a pre-booted Rails process on hand to completely skip parts of the boot process the next time it's needed. The two tools work well together.

Environment variables

require 'bootsnap/setup' behavior can be changed using environment variables:

• BOOTSNAP_CACHE_DIR allows to define the cache location.
• BOOTSNAP_CONFIG allows to change the default config location (config/bootsnap.rb).
• DISABLE_BOOTSNAP allows to entirely disable bootsnap.
• DISABLE_BOOTSNAP_LOAD_PATH_CACHE allows to disable load path caching.
• DISABLE_BOOTSNAP_COMPILE_CACHE allows to disable ISeq and YAML caches.
• BOOTSNAP_READONLY configure bootsnap to not update the cache on miss or stale entries.
• BOOTSNAP_LOG configure bootsnap to log all caches misses to STDERR.
• BOOTSNAP_STATS log hit rate statistics on exit. Can't be used if BOOTSNAP_LOG is enabled.
• BOOTSNAP_IGNORE_DIRECTORIES a comma separated list of directories that shouldn't be scanned. Useful when you have large directories of non-ruby files inside $LOAD_PATH. It defaults to ignore any directory named node_modules.

Environments

All Bootsnap features are enabled in development, test, production, and all other environments according to the configuration in the setup. At Shopify, we use this gem safely in all environments without issue.

If you would like to disable any feature for a certain environment, we suggest changing the configuration to take into account the appropriate ENV var or configuration according to your needs.

Instrumentation

Bootsnap cache misses can be monitored though a callback:

Bootsnap.instrumentation = ->(event, path) { puts "#{event} #{path}" }

event is either :hit, :miss, :stale or :revalidated. You can also call Bootsnap.log! as a shortcut to log all events to STDERR.

To turn instrumentation back off you can set it to nil:

Bootsnap.instrumentation = nil

How does this work?

Bootsnap optimizes methods to cache results of expensive computations, and can be grouped into two broad categories:

This is the beginning of the README. Read the rest at the original. Read the full README ↗