Veja mais em rubyonrails.org: Mais Ruby on Rails

Auto Carregamento e Recarregamento de Constantes (Modo Zeitwerk)

Esse guia documenta como funciona o auto carregamento e o recarregamento no modo zeitwerk.

Depois de ler este guia, você saberá:

1 Introdução

Esse guia documenta auto carregamento no modo zeitwerk, que é algo novo no Rails 6. Se o que você quer ler é sobre o modo classic, leia Auto Carregamento e Recarregamento de Constantes (Modo Classic).

Em um programa Ruby normal, dependências precisam ser carregadas de forma manual. Por exemplo, o controller a seguir utiliza as classes ApplicationController e Post, e normalmente você precisaria colocar alguns require para utilizá-los:

require "application_controller"
require "post"

class PostsController < ApplicationController
  def index
    @posts = Post.all

Isso não é necessário em aplicações Rails, onde as classes e os módulos da aplicação estão disponíveis em todo canto.

class PostsController < ApplicationController
  def index
    @posts = Post.all

Comumente, aplicações Rails só utilizam require para carregar coisas da sua pasta lib, da biblioteca padrão do ruby, do Ruby gems, etc. Ou seja, qualquer coisa que não esteja presente nos caminhos de auto carregamento, explicado a seguir.

2 Habilitando o modo Zeitwerk

O modo zeitwerk de auto carregamento é habilitado por padrão nas aplicações Rails 6 que utilizam CRuby:

# config/application.rb
config.load_defaults 6.0 # habilita o modo zeitwerk usando CRuby

No modo zeitwerk, o Rails utiliza Zeitwerk de forma interna para fazer carregamento automático, recarregamento e eager load. O Rails cria e configura uma instância Zeitwerk dedicada que gerencia o projeto.

Você não configura o Zeitwerk manualmente em uma aplicação Rails. Ao invés disso, você configura a aplicação usando uma configuração portável, que é descrita neste guia. Assim, o Rails traduz essas configurações para o Zeitwerk por você.

3 Estrutura do Projeto

Em uma aplicação Rails, nomes de arquivos precisam corresponder às constantes que definem, com diretórios agindo como namespaces.

Por exemplo, o arquivo app/helpers/users_helper.rb deve definir UsersHelper e o arquivo app/controllers/admin/payments_controller.rb deve definir Admin::PaymentsController.

Por padrão o Rails configura o Zeitwerk para inflexionar nomes de arquivos com String#camelize. Por exemplo, é esperado que app/controllers/users_controller.rb defina a constante UsersController pois

"users_controller".camelize # => UsersController

A seção Customizando Inflexões abaixo documenta maneiras de sobrescrever esse comportamento padrão.

Por favor, verifique a documentação do Zeitwerk para mais detalhes.

4 Autoload Paths

We refer to the list of application directories whose contents are to be autoloaded as autoload paths. For example, app/models. Such directories represent the root namespace: Object.

Autoload paths are called root directories in Zeitwerk documentation, but we'll stay with "autoload path" in this guide.

Within an autoload path, file names must match the constants they define as documented here.

By default, the autoload paths of an application consist of all the subdirectories of app that exist when the application boots ---except for assets, javascript, views,--- plus the autoload paths of engines it might depend on.

For example, if UsersHelper is implemented in app/helpers/users_helper.rb, the module is autoloadable, you do not need (and should not write) a require call for it:

$ bin/rails runner 'p UsersHelper'

Autoload paths automatically pick any custom directories under app. For example, if your application has app/presenters, or app/services, etc., they are added to autoload paths.

The array of autoload paths can be extended by mutating config.autoload_paths, in config/application.rb, but nowadays this is discouraged.

Please, do not mutate ActiveSupport::Dependencies.autoload_paths, the public interface to change autoload paths is config.autoload_paths.


Autoload paths are added to $LOAD_PATH by default. However, Zeitwerk uses absolute file names internally, and your application should not issue require calls for autoloadable files, so those directories are actually not needed there. You can opt-out with this flag:

config.add_autoload_paths_to_load_path = false

That may speed legit require calls a bit, since there are less lookups. Also, if your application uses Bootsnap, that saves the library from building unnecessary indexes, and saves the RAM they would need.

6 Reloading

Rails automatically reloads classes and modules if application files change.

More precisely, if the web server is running and application files have been modified, Rails unloads all autoloaded constants just before the next request is processed. That way, application classes or modules used during that request are going to be autoloaded, thus picking up their current implementation in the file system.

Reloading can be enabled or disabled. The setting that controls this behavior is config.cache_classes, which is false by default in development mode (reloading enabled), and true by default in production mode (reloading disabled).

Rails detects files have changed using an evented file monitor (default), or walking the autoload paths, depending on config.file_watcher.

In a Rails console there is no file watcher active regardless of the value of config.cache_classes. This is so because, normally, it would be confusing to have code reloaded in the middle of a console session, the same way you generally want an individual request to be served by a consistent, non-changing set of application classes and modules.

However, you can force a reload in the console by executing reload!:

irb(main):001:0> User.object_id
=> 70136277390120
irb(main):002:0> reload!
=> true
irb(main):003:0> User.object_id
=> 70136284426020

as you can see, the class object stored in the User constant is different after reloading.

6.1 Reloading and Stale Objects

It is very important to understand that Ruby does not have a way to truly reload classes and modules in memory, and have that reflected everywhere they are already used. Technically, "unloading" the User class means removing the User constant via Object.send(:remove_const, "User").

Therefore, code that references a reloadable class or module, but that is not executed again on reload, becomes stale. Let's see an example next.

Let's consider this initializer:

# config/initializers/configure_payment_gateway.rb
$PAYMENT_GATEWAY = Rails.env.production? ? RealGateway : MockedGateway

The idea would be to use $PAYMENT_GATEWAY in the code, and let the initializer set that to the actual implementation depending on the environment.

On reload, MockedGateway is reloaded, but $PAYMENT_GATEWAY is not updated because initializers only run on boot. Therefore, it won't reflect the changes.

There are several ways to do this safely. For instance, the application could define a class method PaymentGateway.impl whose definition depends on the environment; or could define PaymentGateway to have a parent class or mixin that depends on the environment; or use the same global variable trick, but in a reloader callback, as explained below.

Let's see other situations that involve stale class or module objects.

Check this Rails console session:

irb> joe = User.new
irb> reload!
irb> alice = User.new
irb> joe.class == alice.class
=> false

joe is an instance of the original User class. When there is a reload, the User constant evaluates to a different, reloaded class. alice is an instance of the current one, but joe is not, his class is stale. You may define joe again, start an IRB subsession, or just launch a new console instead of calling reload!.

Another situation in which you may find this gotcha is subclassing reloadable classes in a place that is not reloaded:

# lib/vip_user.rb
class VipUser < User

if User is reloaded, since VipUser is not, the superclass of VipUser is the original stale class object.

Bottom line: do not cache reloadable classes or modules.

6.2 Autoloading when the application boots

Applications can safely autoload constants during boot using a reloader callback:

Rails.application.reloader.to_prepare do
  $PAYMENT_GATEWAY = Rails.env.production? ? RealGateway : MockedGateway

That block runs when the application boots, and every time code is reloaded.

For historical reasons, this callback may run twice. The code it executes must be idempotent.

However, if you do not need to reload the class, it is easier to define it in a directory which does not belong to the autoload paths. For instance, lib is an idiomatic choice, it does not belong to the autoload paths by default but it belongs to $LOAD_PATH. Then, in the place the class is needed at boot time, just perform a regular require to load it.

For example, there is no point in defining reloadable Rack middleware, because changes would not be reflected in the instance stored in the middleware stack anyway. If lib/my_app/middleware/foo.rb defines a middleware class, then in config/application.rb you write:

require "my_app/middleware/foo"
config.middleware.use MyApp::Middleware::Foo

To have changes in that middleware reflected, you need to restart the server.

7 Eager Loading

In production-like environments it is generally better to load all the application code when the application boots. Eager loading puts everything in memory ready to serve requests right away, and it is also CoW-friendly.

Eager loading is controlled by the flag config.eager_load, which is enabled by default in production mode.

The order in which files are eager loaded is undefined.

if the Zeitwerk constant is defined, Rails invokes Zeitwerk::Loader.eager_load_all regardless of the application autoloading mode. That ensures dependencies managed by Zeitwerk are eager loaded.

8 Single Table Inheritance

Single Table Inheritance is a feature that doesn't play well with lazy loading. Reason is, its API generally needs to be able to enumerate the STI hierarchy to work correctly, whereas lazy loading defers loading classes until they are referenced. You can't enumerate what you haven't referenced yet.

In a sense, applications need to eager load STI hierarchies regardless of the loading mode.

Of course, if the application eager loads on boot, that is already accomplished. When it does not, it is in practice enough to instantiate the existing types in the database, which in development or test modes is usually fine. One way to do that is to throw this module into the lib directory:

module StiPreload
  unless Rails.application.config.eager_load
    extend ActiveSupport::Concern

    included do
      cattr_accessor :preloaded, instance_accessor: false

    class_methods do
      def descendants
        preload_sti unless preloaded

      # Constantizes all types present in the database. There might be more on
      # disk, but that does not matter in practice as far as the STI API is
      # concerned.
      # Assumes store_full_sti_class is true, the default.
      def preload_sti
        types_in_db = \

        types_in_db.each do |type|
          logger.debug("Preloading STI type #{type}")

        self.preloaded = true

and then include it in the STI root classes of your project:

# app/models/shape.rb
require "sti_preload"

class Shape < ApplicationRecord
  include StiPreload # Only in the root class.
# app/models/polygon.rb
class Polygon < Shape
# app/models/triangle.rb
class Triangle < Polygon

9 Customizing Inflections

By default, Rails uses String#camelize to know which constant should a given file or directory name define. For example, posts_controller.rb should define PostsController because that is what "posts_controller".camelize returns.

It could be the case that some particular file or directory name does not get inflected as you want. For instance, html_parser.rb is expected to define HtmlParser by default. What if you prefer the class to be HTMLParser? There are a few ways to customize this.

The easiest way is to define acronyms in config/initializers/inflections.rb:

ActiveSupport::Inflector.inflections(:en) do |inflect|
  inflect.acronym "HTML"
  inflect.acronym "SSL"

Doing so affects how Active Support inflects globally. That may be fine in some applications, but you can also customize how to camelize individual basenames independently from Active Support by passing a collection of overrides to the default inflectors:

# config/initializers/zeitwerk.rb
Rails.autoloaders.each do |autoloader|
    "html_parser" => "HTMLParser",
    "ssl_error"   => "SSLError"

That technique still depends on String#camelize, though, because that is what the default inflectors use as fallback. If you instead prefer not to depend on Active Support inflections at all and have absolute control over inflections, configure the inflectors to be instances of Zeitwerk::Inflector:

# config/initializers/zeitwerk.rb
Rails.autoloaders.each do |autoloader|
  autoloader.inflector = Zeitwerk::Inflector.new
    "html_parser" => "HTMLParser",
    "ssl_error"   => "SSLError"

There is no global configuration that can affect said instances, they are deterministic.

You can even define a custom inflector for full flexibility. Please, check the Zeitwerk documentation for further details.

10 Troubleshooting

The best way to follow what the loaders are doing is to inspect their activity.

The easiest way to do that is to throw


to config/application.rb after loading the framework defaults. That will print traces to standard output.

If you prefer logging to a file, configure this instead:

Rails.autoloaders.logger = Logger.new("#{Rails.root}/log/autoloading.log")

The Rails logger is still not ready in config/application.rb, but it is in initializers:

# config/initializers/log_autoloaders.rb
Rails.autoloaders.logger = Rails.logger

11 Rails.autoloaders

The Zeitwerk instances managing your application are available at


The former is the main one. The latter is there mostly for backwards compatibility reasons, in case the application has something in config.autoload_once_paths (this is discouraged nowadays).

You can check if zeitwerk mode is enabled with


12 Differences with Classic Mode

12.1 Ruby Constant Lookup Compliance

classic mode cannot match constant lookup semantics due to fundamental limitations of the technique it is based on, whereas zeitwerk mode works like Ruby.

For example, in classic mode defining classes or modules in namespaces with qualified constants this way

class Admin::UsersController < ApplicationController

was not recommended because the resolution of constants inside their body was brittle. You'd better write them in this style:

module Admin
  class UsersController < ApplicationController

In zeitwerk mode that does not matter anymore, you can pick either style.

The resolution of a constant could depend on load order, the definition of a class or module object could depend on load order, there was edge cases with singleton classes, oftentimes you had to use require_dependency as a workaround, .... The guide for classic mode documents these issues.

All these problems are solved in zeitwerk mode, it just works as expected, and require_dependency should not be used anymore, it is no longer needed.

12.2 Less File Lookups

In classic mode, every single missing constant triggers a file lookup that walks the autoload paths.

In zeitwerk mode there is only one pass. That pass is done once, not per missing constant, and so it is generally more performant. Subdirectories are visited only if their namespace is used.

12.3 Underscore vs Camelize

Inflections go the other way around.

In classic mode, given a missing constant Rails underscores its name and performs a file lookup. On the other hand, zeitwerk mode checks first the file system, and camelizes file names to know the constant those files are expected to define.

While in common names these operations match, if acronyms or custom inflection rules are configured, they may not. For example, by default "HTMLParser".underscore is "html_parser", and "html_parser".camelize is "HtmlParser".

12.4 More Differences

There are some other subtle differences, please check this section of Upgrading Ruby on Rails guide for details.

13 Classic Mode is Deprecated

By now, it is still possible to use classic mode. However, classic is deprecated and will be eventually removed.

New applications should use zeitwerk mode (which is the default), and applications being upgrade are strongly encouraged to migrate to zeitwerk mode. Please check the Upgrading Ruby on Rails guide for details.

14 Opting Out

Applications can load Rails 6 defaults and still use the classic autoloader this way:

# config/application.rb
config.load_defaults 6.0
config.autoloader = :classic

That may be handy if upgrading to Rails 6 in different phases, but classic mode is discouraged for new applications.

zeitwerk mode is not available in versions of Rails previous to 6.0.


Você é incentivado a ajudar a melhorar a qualidade deste guia.

Por favor, contribua se vir qualquer erros, inclusive erros de digitação. Para começar, você pode ler nossa sessão de contribuindo com a documentação.

Você também pode encontrar conteúdo incompleto ou coisas que não estão atualizadas. Por favor, adicione qualquer documentação em falta na main do Rails. Certifique-se de checar o Edge Guides (en-US) primeiro para verificar se o problema já foi resolvido ou não no branch main. Verifique as Diretrizes do Guia Ruby on Rails para estilo e convenções.

Se, por qualquer motivo, você encontrar algo para consertar, mas não conseguir consertá-lo, por favor abra uma issue no nosso Guia.

E por último, mas não menos importante, qualquer tipo de discussão sobre a documentação do Ruby on Rails é muito bem vinda na lista de discussão rubyonrails-docs e nas issues do Guia em português.

dark theme icon