Ruby include vs extend: Understanding Modules and Mixins

By the end of this page, you will understand what include and extend do in Ruby, how they affect method lookup, why one adds instance methods and the other adds class-level behavior, and when to use each in real code.

Ruby modules are a way to group reusable behavior.

When you add a module to a class, the key question is: who should receive those methods?

• With include, the module is inserted into the class's ancestor chain so its methods become available to instances of that class.
• With extend, the module is added to a specific object's singleton class, so its methods become available to that object itself.

That is why this works differently for classes:

• A class in Ruby is also an object
• So when you extend SomeModule inside a class, you are adding methods to the class object, which appear as class methods

Why this matters

This distinction shows up everywhere in Ruby:

• sharing behavior between instances of many classes
• adding utility methods to a class
• building DSLs
• Rails concerns and macros
• metaprogramming patterns

The short version is:

• include = instances gain the module's methods
• extend = the receiver itself gains the module's methods

So yes, your summary is mostly correct. The deeper idea is that extend is not specifically about class methods. It adds methods to any object you call it on. If that object happens to be a class, they look like class methods.

Think of a module as a toolkit.

• include puts the toolkit into every worker created from a class
• extend puts the toolkit directly into the factory itself

If CarFactory includes a module, then each car built by the factory can use those tools. If CarFactory extends a module, then the factory can use those tools directly.

Another way to see it:

• include affects future instances
• extend affects the current object

Since classes are objects in Ruby, extending a class means the class object gets those methods.

Core syntax

module MyModule
  def greet
    "Hello"
  end
end

class Person
  include MyModule
end

class Robot
  extend MyModule
end

Example: include

module Speakable
  def speak
    "I can speak"
  end
end

class Human
  include Speakable
end

person = Human.new
puts person.speak
# => I can speak

What happened?

• Speakable defines an instance method: speak
• includes the module

Consider this code:

module ReusableModule
  def module_method
    "Module Method: Hi there!"
  end
end

class ClassThatIncludes
  include ReusableModule
end

class ClassThatExtends
  extend ReusableModule
end

Step-by-step

1. Ruby defines the module

module ReusableModule

Ruby creates a module object named ReusableModule.

2. The method is stored in the module

def module_method
  "Module Method: Hi there!"
end

This becomes an instance method of the module, ready to be mixed into something else.

3. ClassThatIncludes includes the module

When to use include

Use include when every instance of a class should share common behavior.

Examples:

• formatting methods for model objects
• permission-checking behavior for service objects
• reusable validation helpers
• logging behavior for instances
• comparable behavior like Enumerable

module Printable
  def print_name
    puts name
  end
end

class User
  include Printable

  attr_reader :name

  def initialize(name)
    @name = name
  end
end

When to use extend

Use extend when you want to add behavior to one specific object, often a class.

Examples:

• class-level helper methods
• configuration APIs
• DSL-style macros
• utility behavior on a single object

In real Ruby projects, include and extend are often used in patterns rather than isolation.

1. Shared instance behavior with include

A common use is to keep classes small by moving reusable instance methods into modules.

module TimestampFormatter
  def formatted_time(time)
    time.strftime("%Y-%m-%d")
  end
end

class Report
  include TimestampFormatter
end

2. Class-level APIs with extend

Libraries often use extend to add class methods that act like macros.

module Configurable
  def setting(name, value)
    @settings ||= {}
    @settings[name] = value
  end

  def settings
     || {}
  


 
   
  setting , 

1. Thinking extend only works for classes

It works on any object.

module Extra
  def hello
    "hello"
  end
end

obj = Object.new
obj.extend(Extra)
puts obj.hello

2. Expecting include to create class methods

Broken example:

module Helper
  def do_work
    "done"
  end
end

class Task
  include Helper
end

Task.do_work
# NoMethodError

Fix

Call the method on an instance:

Task.new.do_work

Or use extend if you want a class method:

include vs prepend

# Define a module for mixing in
module MyModule
  def hello
    "hello"
  end
end

# include => instance methods
class A
  include MyModule
end
A.new.hello

# extend => methods on the object itself
class B
  extend MyModule
end
B.hello

Rules to remember

• include adds module methods to instances of the class
• extend adds module methods to the receiver itself
• classes are objects too, so extend in a class body creates class methods
• extend can be used on any object, not just classes
• def self.name inside a module defines a module-level method, not a mixin method

Quick checks

ClassName.ancestors

Shows modules included for instance lookup.

Is extend only for adding class methods in Ruby?

No. extend adds methods to any specific object. If that object is a class, the methods appear as class methods.

Why does include create instance methods?

Because the module is inserted into the class's ancestor chain for instance method lookup.

Can I use both include and extend with the same module?

Yes. Then the module's methods can be available both on instances and on the class object.

What is the difference between include and require in Ruby?

require loads a file. include mixes a module's methods into a class or module.

How do I add both instance and class methods from one module?

A common pattern is to include the module and, inside its included hook, extend a nested ClassMethods module.

Does include copy methods into the class?

• Modules in Ruby — the foundation for include and extend
• Mixins — the general technique of sharing behavior through modules
• Class methods — important for understanding what extend often creates
• Instance methods — important for understanding what include provides
• Singleton classes — explains how extend adds methods to one object
• Method lookup path — helps explain why Ruby finds mixed-in methods
• prepend in Ruby — a related way to mix in behavior with different lookup priority
• self in Ruby — useful for understanding what object is receiving extend
• require vs include — commonly confused by beginners
• Ruby metaprogramming basics — broader context for module hooks and dynamic behavior