By Fred Heath

Get the Lowdown on Ruby Modules

By Fred Heath

Modules are wonderfully flexible language constructs which can be applied to a wide variety of use cases, such as namespacing, inheritance, and decorating. However, some developers are still confused about how modules work and how they interact with their own code. This article aims to shed some light on Modules and their usage.

The Ruby Object Model (ROM)

As with most things Ruby, modules are very easy to use, once we understand how they fit into the Ruby Object Model (ROM). The ROM is populated by objects that are classes (class-objects, a.k.a. Classes) and objects that are instances of classes (instance-objects). Oh, and Modules too! Let’s create a couple of classes:

class Car
  def drive

class Trabant < Car

If we visualize the ROM on a 2D plain, then the object hierarchy looks like this:

The class-objects our class is derived from live above our class. The class-objects deriving from our class live below it. To the right of our class, lives its eigenclass (a.k.a singleton class or meta-class). Eigenclasses are class-objects, too, and as such, they have superclasses, usually the eigenclass of our class’s superclass or, in the case of instance objects, the class of the object itself. A full description of eigenclasses is beyond the scope of this article and deserves an article in itself. For now, don’t worry too much about them, just know that they are there and that they have a purpose.

So, what happens when we instantiate an object based on our class?

my_car =

Ruby will create our object’s eigenclass directly under our Car class. It will place our new instance (my_car) to the left of its eigenclass and outside the object hierarchy.

We can actually verify all this in Ruby’s irb:

        => Car 
> my_car.singleton_class
        => #<Class:#<Car:0x0000000165e568>> 
> my_car.singleton_class.class
        => Class 
> my_car.singleton_class.superclass
        => Car

Method Lookup

Let’s call a method on our object?

The object we call a method on (my_car) is called the receiver object. Ruby has a very simple algorithm for looking up methods:

receiver –> look to the right –> look up

When we call the drive method on my_car, Ruby will first look to the right in my_car‘s eigenclass object. It won’t find the method definition there, so it will look up to the Car objects, where it will find the definition of drive. Knowing this makes understanding how to use modules easy.

Modules in Their Environment

There are three things we can do with a module:

  1. Include it in our class-objects
  2. Prepend it to our class-objects
  3. Extend our class objects or instance objects with it

The Helicopter Rule


Ruby slots Modules into the ROM by following what I call the Helicopter rule. I call it that because in my warped imagination the diagram looks like a helicopter, as shown in the above image. The Helicopter Rule means:

  1. Including a module in our object will place it directly above our object.
  2. Prepending a module to our object will place it directly below our object.
  3. Extending our object with a module will place it directly above our object’s eigenclass.

Let’s verify this in code:

  module A; end
  module B; end
  module C; end

  class MyClass
    include A
    prepend B
    extend C

   => [B, MyClass, A, Object, Kernel, BasicObject] 
   => [#<Class:MyClass>, C, #<Class:Object>, #<Class:BasicObject>, Class, Module, Object, Kernel, BasicObject]

We observe that module A is placed directly above MyClass (included), module B is placed directly below MyClass (prepended) and module C is placed directly above MyClass‘s eigenclass (extended)

NOTE: Calling the superclass method on a class object will give us the next higher class in the ancestor chain above our class. However, as Modules aren’t technically Classes, superclass won’t show us any modules directly above our class. For that, we need to use the ancestors method.


Let’s open our Car class and include a Module:

module V12Engine
  def start; "...roar!"; end

class Car
  include V12Engine

When we include a module in our class, Ruby places it directly above our class. This means that when we call a method on our instance object, Ruby will find it in the object hierarchy and run it:

=>  ...roar!"


This is the usual way to implement multiple inheritance in Ruby, as we can include many modules in our class, thereby giving it a lot of extra functionality. Modules used to that effect are known as “mixins”.

Note: It also means that if we define a method with the same name in our Car class, Ruby will find and run this instead and our Module method will never be called.


When we prepend a module to our class, Ruby places it directly below our class. The means that, during method lookup, Ruby will encounter the methods defined in the Module before the methods defined in our Class. As a result, any module methods will effectively override any class methods with the same name. Let’s try this:

module ElectricEngine
  def drive; "eco-driving!"; end

class Car
  prepend ElectricEngine

my_car =
=> eco-driving!


Observe that if we now call the drive method on my_car, we’re getting the prepended module’s implementation of the method, instead of the Car class implementation. Prepending modules can be very useful when we want to scope our method logic according to various external conditions. Say, for example, we want to measure our methods’ performance when running in a test environment. Instead of polluting our methods with if statements and instrumentation code, we can put our specialized methods in a separate module and prepend the module to our class only if we’re in a test environment:

module Instrumentable
  require 'objspace'
  def drive
    puts ObjectSpace.count_objects[:FREE]
    puts ObjectSpace.count_objects[:FREE]

class Car
  prepend Instrumentable if ENV['RACK_ENV'] = 'test'

my_car =
=> 711
=> driving
=> 678

Including and Prepending with Instances

As instance objects are placed outside the ROM hierarchy, there is no ‘above’ or ‘below’ them where we can place modules (see the Method Lookup diagram). This means that we cannot include or prepend modules to instance objects.

Extending Classes

When we extend our class object with a module, Ruby places it directly above our object’s eigenclass:

module SuperCar
  def fly; "flying!"; end

class Car
  extend SuperCar

Our Car instances can’t access the fly method, as the method lookup will start at the car instance, my_car, move right to the eigenclass my_car and then up to the Car class and its ancestors. The fly method will never be found in that path:
=> NoMethodError: undefined method `fly' for #<Car:0x000000019ae8d0>

But what if we call the method on our class object instead?
=> flying

Our receiver object is now the Car class itself. Ruby will first look to the right (Car) and then up to SuperCar module where, lo and behold, it will find the fly method. So, extending a Class with a Module, effectively gives our Class new class methods.

Extending Instances

We can extend a specific instance of our Class, like so:


This will place the SuperCar module above our object’s eigen-class.

Module instance extend.png

We can now call fly on our car:
=> flying

But not on any other car:
=> NoMethodError: undefined method `fly' for #<Car:0x000000012ae868>

Extending an instance object with a Module is a great way to dynamically decorate specific Class instances. I use it all the time in Rails applications to easily and quickly implement the Presenter pattern (i.e. model objects that I want to show in my views)

<%=  my_article.extend(Presentable).title %>


There’s much more to Modules than can be covered in a single article. Understanding how Modules fit into the Ruby Object Model is essential in order to use them fully and creatively. Let us know how Modules fit into your designs and all the cool things you do with them!

  • Marko Pavlovic

    Excellent article, very informative. Thanks!

    • Fred@Bootstrap

      Thanks Marko, I appreciate that/

  • rizal muthi

    Good article. Easy to understand. Finally.

    Anyway, there is a little bit problem with the image on the Prepending section, it shows the Including images instead. Hope you can fix that :D


    • Fred@Bootstrap

      thanks for spotting this Rizal, it was already on my radar and should be fixed soon!

  • Generator

    Thanks for cool article, just one remark: there should be

    if ENV['RACK_ENV'] == 'test'

    instead of

    if ENV['RACK_ENV'] = 'test'

    • Fred@Bootstrap

      Thanks Generator, well spotted!

  • NeutralDog

    Very nice Article, Good job Fred!

    • Fred@Bootstrap

      thank you, glad you enjoyed it!

  • Pretty cool. Thanks for sharing what you know. Very much appreciate it.

    • Fred@Bootstrap

      thanks Francisco, my pleasure!

Get the latest in Ruby, once a week, for free.