Bootsnap

Bootsnap optimizes Ruby application boot times through two primary mechanisms:

1. Path Pre-Scanning: Modifies Kernel#require and Kernel#load to eliminate expensive $LOAD_PATH scans. It uses a cache to immediately resolve the full expanded path of a required file, avoiding multiple failed filesystem lookups.
2. Compilation Caching:
   • Caches Ruby bytecode compilation results via RubyVM::InstructionSequence.load_iseq.
   • Caches YAML.load_file and JSON.load_file results by converting them into a faster MessagePack (or Marshal) format.

Path entries are classified as stable (e.g., Ruby install prefix, Gem.path, or Bundler.bundle_path) which do not expire, or volatile (everything else) which are re-scanned every 30 seconds.

Avoid using Bootsnap in the following scenarios:

• Alternative Ruby Engines: Bootsnap relies heavily on MRI-specific features; parts of it are disabled on other engines.
• Non-local Filesystems: Bootsnap requires a fast filesystem for its cache directory (defaulting to tmp/cache). Using a network mount for the cache directory will likely degrade application performance.

To use Bootsnap in a Rails application, add the gem to your Gemfile and require the setup script in config/boot.rb immediately after require 'bundler/setup'.

Important Requirements:

• Bootsnap requires a writable directory for its cache. By default, it uses tmp/cache. If you are in a read-only environment, you must either provide a writable path via ENV['BOOTSNAP_CACHE_DIR'] or remove the requirement.
• Bootsnap does not automatically clean up its cache. You should periodically purge tmp/cache/bootsnap* to prevent deployment slowdowns.

# Gemfile
gem 'bootsnap', require: false

# config/boot.rb
require 'bundler/setup'
require 'bootsnap/setup'

To enable YAML compilation caching in Bootsnap, call Bootsnap::CompileCache::YAML.install! with the desired cache directory path. This will initialize the cache and prepend the necessary patch to the ::YAML singleton class.

Note: The cache directory will be automatically suffixed with -yaml (or yaml if the path ends with a slash) to separate it from other Bootsnap caches.

When building cross-platform Docker images using QEMU (e.g., via docker buildx), Bootsnap precompilation may cause forked processes to hang. To resolve this, disable parallelization during the precompile step using the -j 0 flag.

$ bundle exec bootsnap precompile -j 0 --gemfile app/ lib/ config/

If you are not using Rails, or require granular control, you can manually call Bootsnap.setup immediately after require 'bundler/setup'. This allows you to specify the cache directory, directories to ignore, and which specific compilation caches to enable.

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
  load_path_cache:      true,                 # Optimize the LOAD_PATH with a cache
  compile_cache_iseq:   true,                 # Compile Ruby code into ISeq cache
  compile_cache_yaml:   true,                 # Compile YAML into a cache
  readonly:             true,                 # Use caches but don't update them on miss
)

You can substitute the default Ruby compiler with custom logic via the Bootsnap configuration file (defaults to config/bootsnap.rb). This is useful for implementing code preprocessing, such as enabling frozen string literals for application code while leaving gems untouched.

Note: Full support for this feature requires Ruby 4.0.4 or newer. On older versions, it may fail if the Coverage module is enabled.

# config/bootsnap.rb
gems_root = File.join(Bundler.bundle_path.cleanpath, "")
app_root =  File.join(Dir.pwd, "")
Bootsnap::CompileCache::ISeq.compiler_selector = ->(path) do
  # Enable `frozen_string_literal: true` for app code, but not gems.
  if path.start_with?(app_root) && !path.start_with?(gems_root)
    Bootsnap::CompileCache::ISeq::FROZEN_STRING_LITERAL
  else
    Bootsnap::CompileCache::ISeq::DEFAULT
  end
end

You can monitor cache performance by assigning a proc to Bootsnap.instrumentation. The proc receives two arguments: event (one of :hit, :miss, :stale, or :revalidated) and the path.

Alternatively, you can use Bootsnap.log! to quickly log all events to STDERR. To disable instrumentation, set Bootsnap.instrumentation to nil.

You can set the directory where ISeq binaries are stored using Bootsnap::CompileCache::ISeq.cache_dir=.

• If the path ends with /, the sub-directory iseq is used.
• If the path does not end with /, the suffix -iseq is appended to the path.

You can modify the behavior of require 'bootsnap/setup' using the following environment variables: