Ruby Module Keyword

last modified October 18, 2026

This tutorial explains how to use Ruby's module keyword. Modules provide namespaces and mixin functionality in Ruby programs.

The module keyword defines a namespace for methods and constants. Modules cannot be instantiated like classes but can be included in classes.

Modules serve two primary purposes: namespacing and mixins. They help organize code and enable multiple inheritance-like behavior through mixins.

Basic Module Definition

This example shows the simplest module definition containing constants and methods. Modules encapsulate related functionality.

basic_module.rb

module Greeter
  DEFAULT_GREETING = "Hello"

  def self.say_hello(name)
    puts "#{DEFAULT_GREETING}, #{name}!"
  end
end

Greeter.say_hello("Alice")
puts Greeter::DEFAULT_GREETING

The Greeter module contains a constant and a module method. We access them using :: for constants and . for methods. A module can also be reopened later to add methods or constants, just like a class.

Module as Namespace

Modules prevent naming collisions by acting as containers. This example shows how modules organize related classes.

namespace.rb

module Animals
  class Dog
    def speak
      puts "Woof!"
    end
  end

  class Cat
    def speak
      puts "Meow!"
    end
  end
end

dog = Animals::Dog.new
cat = Animals::Cat.new

dog.speak
cat.speak

The Animals module contains Dog and Cat classes. We reference them with the module prefix to avoid global namespace pollution. Inside the module, constant lookup is lexical, so nested classes can refer to constants defined alongside them.

Module as Mixin

Modules can be mixed into classes using include. This provides multiple inheritance-like behavior.

mixin.rb

module Debuggable
  def debug_info
    "#{self.class} (id: #{object_id})"
  end
end

class Product
  include Debuggable
end

book = Product.new
puts book.debug_info

The Debuggable module adds debug_info to any class that includes it. include inserts the module into the class's ancestor chain, so its instance methods become available to instances.

Extend vs Include

Ruby offers two ways to mix in modules: include for instance methods and extend for methods on the extending object.

extend_include.rb

module ClassMethods
  def class_info
    "Class #{self}"
  end
end

module InstanceMethods
  def instance_info
    "Instance of #{self.class}"
  end
end

class Demo
  extend ClassMethods
  include InstanceMethods
end

puts Demo.class_info
puts Demo.new.instance_info

extend adds the module's methods to the class object as singleton methods, while include adds them as instance methods. This distinction is crucial for proper module usage.

Module Functions

The module_function method makes a method callable on the module itself and keeps a private instance version for inclusion. This is useful for utility modules.

module_function.rb

module MathHelper
  module_function

  def double(value)
    value * 2
  end
end

puts MathHelper.double(21)

class Calculator
  include MathHelper

  def compute
    double(5)
  end
end

puts Calculator.new.compute

After module_function, double can be called as MathHelper.double. When the module is included, the same method is available as a private instance method, which is why it can be called without a receiver inside compute.

Module Composition

Modules can be nested, and their parts can be included separately, enabling composition patterns. This example shows nested module functionality.

composition.rb

module Features
  module Printable
    def print
      puts "Printing #{self}"
    end
  end

  module Serializable
    def serialize
      Marshal.dump(self)
    end
  end
end

class Document
  include Features::Printable
  include Features::Serializable
end

doc = Document.new
doc.print
puts doc.serialize.size

The Features module contains two submodules. We include them separately in the Document class for modular functionality.

Module with Class Methods

This pattern adds class methods through a module using the self.included hook. It's a common Ruby idiom.

class_methods.rb

module Tagging
  def self.included(base)
    base.extend(ClassMethods)
  end

  module ClassMethods
    def tags
      @tags ||= []
    end
  end

  def add_tag(tag)
    self.class.tags << tag
  end
end

class Post
  include Tagging
end

post = Post.new
post.add_tag("ruby")
puts Post.tags.inspect

When Tagging is included, it automatically extends the class with ClassMethods. This provides both instance and class methods.

Refinements for Isolation

Refinements, declared with refine inside a module and activated with using, isolate method additions that might conflict with other code. This example demonstrates safe method addition.

isolation.rb

module MathUtils
  refine Integer do
    def factorial
      (1..self).inject(:*) || 1
    end
  end
end

# Regular Integer has no factorial method
# puts 5.factorial # Would raise NoMethodError

using MathUtils

puts 5.factorial  # Now works: 120

The refine method adds methods only where explicitly requested with using. This prevents global monkey-patching issues.

Source

Ruby Modules Documentation

This tutorial covered Ruby modules with examples showing namespacing, mixins, composition, and refinement patterns. Modules are fundamental to Ruby design.

Author

My name is Jan Bodnar, and I am a passionate programmer with extensive programming experience. I have been writing programming articles since 2007. To date, I have authored over 1,400 articles and 8 e-books. I possess more than ten years of experience in teaching programming.

List all Ruby tutorials.

Ebooks