skip to content

Autoloading & Reloading

Rails autoloads app/ with Zeitwerk, mapping file names to constants, reloads code in development and eager loads it in production. Interviewers probe naming errors and stale references after a reload.

part ofRuby on Railsread it →
on this pageshow

explore

questions

5

In a Rails 8.1 app, why does an edited model take effect without a restart in development but not in production?

level: juniorimportance: must knowfreq 55%

answer

  1. two settings per environment
  2. enable_reloading: true only in development
  3. eager_load: true only in production
  4. test eager loads when CI is set
  5. reload! in the console

basics

~20 s

Development sets config.enable_reloading = true, so after a file changes Rails unloads autoloaded application constants before the next request, which autoloads fresh code. Production sets enable_reloading = false and eager_load = true, loading all code once at boot.

solid answer

~40 s

Two settings in `config/environments/*.rb` decide it. `config.enable_reloading` is `true` in the generated `development.rb` and `false` in `test.rb` and `production.rb`; `config.cache_classes` is its older inverse spelling. With reloading on, a file watcher notices a change in the autoload paths, and before the next request Rails unloads the constants the main Zeitwerk loader autoloaded, so the request autoloads the edited code. `config.eager_load` is `false` in development, `true` in production and `ENV["CI"].present?` in test, so production loads every file at boot and never reloads. In `bin/rails console` no watcher runs; `reload!` reloads by hand. Reloading covers only autoloaded code: initializers, `config/application.rb` and gems still need a restart.

code

ruby · 11 lines
ruby
# config/environments/development.rb (generated)
Rails.application.configure do
  config.enable_reloading = true
  config.eager_load = false
end

# config/environments/production.rb (generated)
Rails.application.configure do
  config.enable_reloading = false
  config.eager_load = true
end

go deeper

for a junior

Remember the two switches and their values per environment, and that the console needs reload! after an edit.

for a middle

Explain the reload cycle: file watcher, unloading the main autoloader's constants before the next request, autoloading fresh code; and what never reloads.

for a senior

Justify eager loading in production by boot-time errors and copy-on-write memory, and know where rake_eager_load and the CI switch change that picture.

for a principal

Weigh development speed against fidelity: when to eager load in CI or locally to catch loading bugs that lazy loading hides.

## Two settings, three environments Whether edited code shows up without a restart is decided by two settings that every generated `config/environments/*.rb` file spells out: | Setting | development | test | production | |---|---|---|---| | `config.enable_reloading` | `true` | `false` | `false` | | `config.eager_load` | `false` | `ENV["CI"].present?` | `true` | - **`config.enable_reloading`** decides whether application constants can be unloaded and loaded again while the process runs. `config.cache_classes` is the older name with the opposite meaning (`cache_classes == !enable_reloading`) and is still accepted. - **`config.eager_load`** decides whether all code in the eager-load paths is loaded at boot, instead of lazily on first reference. ## What a reload does in development With reloading enabled, Rails configures the main Zeitwerk loader (`Rails.autoloaders.main`) with reloading on. A request cycle looks like this: 1. A file watcher tracks the autoload paths. The default class is `ActiveSupport::FileUpdateChecker`; `ActiveSupport::EventedFileUpdateChecker` is the alternative and needs the `listen` gem. 2. When a watched file changed, Rails unloads every constant the main loader autoloaded **before the next request is processed**. Unloading means removing the constant, as `remove_const` does; Ruby cannot patch a class in place everywhere it is referenced. 3. The request then references `Filing` again, Zeitwerk autoloads `app/models/filing.rb` afresh and the new code runs. Because `config.reload_classes_only_on_change` is `true` by default, nothing is unloaded when no file changed. ## Why production does the opposite Production sets `enable_reloading = false` and `eager_load = true`: - **Everything is loaded at boot.** Requests do not pay for autoloading application code, and memory loaded before a server forks its workers can be shared copy-on-write. - **Errors surface at boot.** A file that defines the wrong constant raises `Zeitwerk::NameError` during the deploy rather than on some later request. An edit to a deployed file therefore needs a new process: a deploy or a restart. ## The console and Rake tasks - **Console:** no file watcher runs in `bin/rails console`, whatever `enable_reloading` says, so a session keeps a consistent set of classes. Call `reload!` to reload by hand; objects built before it still belong to the old class objects. - **Rake tasks:** while a Rake task runs, `config.eager_load` is replaced by `config.rake_eager_load`, which is `false` by default. Production Rake tasks therefore load lazily. ## What reloading never covers Reloading only touches constants that the **main** autoloader manages. These need a restart even in development: - `config/application.rb`, `config/environments/*.rb` and `config/initializers/*.rb`, which run once at boot; - gems and the Gemfile; - code in `config.autoload_once_paths` (or `lib` set up with `config.autoload_lib_once`), which is autoloaded but deliberately not reloaded; - a brand-new top-level directory under `app`, because the autoload paths are fixed at boot. ## When an edit does not show up A short checklist for the common "I changed it and nothing happened" report in development: 1. **Is the code autoloaded?** Only files under the autoload paths are reloaded. Code in an initializer, in `config/application.rb`, in a gem, or in a file loaded with `require` needs a restart. 2. **Is it in the autoload once paths?** Classes in `config.autoload_once_paths`, or in `lib` when the app uses `config.autoload_lib_once`, are autoloaded but never reloaded, on purpose. 3. **Did something capture the old class?** A registry, a constant or a framework setting filled at boot keeps the class object from boot; reloading creates a new one that nobody stored. 4. **Is it the console?** `bin/rails console` never reloads on its own; run `reload!` and rebuild the objects you are holding. 5. **Is reloading on at all?** Check that `config.enable_reloading` is still `true` in `config/environments/development.rb`; an old app may still say `config.cache_classes = false`, which means the same thing. ## Test environment `test.rb` disables reloading because a test run is a single pass. It eager loads only when the `CI` variable is set, so local runs boot quickly while CI loads every file and catches naming errors.

  • Why does a long-open bin/rails console not see an edit to app/models/filing.rb?
    No file watcher runs in the console, regardless of `config.enable_reloading`, so a session keeps one consistent set of classes. Call `reload!` to unload and reload application code. Objects you built before `reload!` still point at the old class object, so rebuild them after reloading.
  • In production, does a Rake task eager load the application?
    Not by default. While a Rake task runs, `config.eager_load` is overridden by `config.rake_eager_load`, which defaults to `false`, so tasks autoload lazily even in production. Set `config.rake_eager_load = true` if a task depends on all code being loaded.

A restaurant kitchen during prep works from loose recipe cards a cook can swap between orders; once service starts, the printed menu is fixed and changing a dish means reprinting it, which is production's restart.

  • Rails reloads every Ruby file in the project on each request in development.
  • Editing config/initializers files takes effect on the next request in development.
  • config.cache_classes = true turns reloading on.
  • Production autoloads lazily, so a misnamed file only fails when a request reaches it.
  • The Rails console reloads changed models automatically before each command.
open as a page

In a Rails 8.1 app, how does Zeitwerk decide which constant app/services/filings/deadline_calculator.rb must define, and how do you check the whole tree?

level: middleimportance: must knowfreq 62%

basics

~10 s

Zeitwerk camelizes each path segment below an autoload path, so app/services/filings/deadline_calculator.rb must define Filings::DeadlineCalculator. bin/rails zeitwerk:check eager loads the app and names any file that defines the wrong constant.

open as a page

In a Rails 8.1 app, why does renaming the class in lib/docket/pdf_exporter.rb to Docket::PDFExporter break production boot with Zeitwerk::NameError?

level: middleimportance: should knowfreq 40%

basics

~10 s

config.autoload_lib puts lib in the autoload and eager-load paths, and Zeitwerk expects pdf_exporter.rb to define Docket::PdfExporter. Production eager loads at boot, finds Docket::PDFExporter instead, and raises Zeitwerk::NameError.

open as a page

In a Rails 8.1 app, config/initializers/exporters.rb registers ClauseRenderer from app/renderers in a registry; why does boot raise NameError, and what goes stale once it is forced to work?

level: seniorimportance: should knowfreq 35%

basics

~20 s

Initializers run before Rails sets up the main autoloader, so reloadable app classes cannot be referenced there. If forced in, the registry keeps the class object from boot, and after a reload it holds a stale class.

open as a page

In a Rails 8.1 app, what do Rails.autoloaders.main.collapse and Rails.autoloaders.main.ignore change, and when would you use each?

level: seniorimportance: nice to knowfreq 22%

basics

~20 s

collapse keeps a directory managed but stops it from being a namespace, so app/models/filings/motion.rb defines Motion. ignore removes files or directories from Zeitwerk entirely, so they are neither autoloaded nor eager loaded and must be required by hand.

open as a page