Ruby Autoload

Reference entry · last updated October 9, 2026

Ruby autoload registers a file to load when a named constant is first accessed in a class or module.[1]

First principles and definitions

A Ruby class name is a constant that refers to a class object. In Shop::Order, Order names the class within Shop. A namespace is a class or module that contains names, allowing different namespaces to contain their own Order constants.[2][6]

Shop.autoload(:Order, path) associates one constant with one file in the Shop namespace. The :Order argument is a symbol naming the constant. Registration does not define the class body; the file supplies that definition when loaded.[1]

Registration and first access

This illustrative example uses two files in one directory. main.rb defines Shop manually, then registers Order. The namespace exists before registration.

# main.rb
module Shop
  autoload :Order, File.expand_path("order.rb", __dir__)
end

p File.basename(Shop.autoload?(:Order)) # => "order.rb"
p Shop::Order.new.total                # => 100
p Shop.autoload?(:Order)               # => nil

# order.rb
module Shop
  class Order
    def total
      100
    end
  end
end

File.expand_path produces an absolute path using __dir__, the directory containing main.rb, as its starting point. This keeps the example independent of the process's working directory.[3][4]

Running ruby main.rb prints "order.rb", 100, and nil. autoload? inspects the pending registration without loading the file. After Shop::Order loads successfully, that registration is consumed and autoload? returns nil.[1]

Autoload and require

require loads a file when the call executes. It returns true when it loads the file and false when the file is already loaded. Ruby autoload uses require when the registered constant is accessed.[4][1]

Zeitwerk

Zeitwerk derives constant names from file paths and sets Ruby autoloads.[7] With lib configured as a root directory, its default naming rules map lib/shop/order.rb to Shop::Order. After loader.setup, accessing that constant loads its file.[5]

If shop contains managed Ruby files and has no matching shop.rb, Zeitwerk can create the Shop module implicitly. The native example above creates Shop itself.[5]

When a managed file loads, Zeitwerk checks that it defines the expected constant. A file mapped to Shop::Order that fails to define it raises Zeitwerk::NameError.[5]

Reloading

Native autoload does not watch for file changes or reload an existing class. Zeitwerk offers reloading separately: loader.enable_reloading must run before loader.setup. Calling loader.reload removes the managed constant definitions and resets it to load current file contents. Concurrent autoloading and reloading require coordination by the application.[1][4][5]

References

^ Ruby 4.0 documentation, Module#autoload and Module#autoload?.
^ Ruby 4.0 documentation, Class.
^ Ruby 4.0 documentation, File.expand_path.
^ Ruby 4.0 documentation, Kernel#require and Kernel#__dir__.
^ Xavier Noria, Zeitwerk README, file structure, autoloading, and reloading.
^ Ruby 4.0 documentation, Modules and classes.
^ Zeitwerk source, Cref#autoload, commit 0616bcd, lines 46–47.