Magic Comments in Ruby

Note (2025): Magic comments in Ruby remain relevant, but their usage has evolved: # encoding: utf-8 → Legacy. UTF-8 is default in modern Ruby, rarely needed. # frozen_string_literal: true → Still widely used for performance and immutability. May become default in the future. # shareable_constant_value: literal → Modern and important for concurrency (Ractors). # warn_indent: true → Useful in legacy style enforcement but mostly replaced by RuboCop/linters. This post is still useful for developers maintaining older codebases or working with concurrency in newer Ruby versions.

We all know and use comments in code. In Ruby, comments start with the # character—the interpreter ignores everything after # on that line.

# This is a comment

However, magic comments are special directives—placed at the top of a source file—that change how Ruby interprets that file. They must be on the first line, or the second line if the first is a shebang (#!). Magic comments affect only the current file.

Common magic comments

coding / encoding

Ruby’s default source encoding is UTF-8. You can set a different encoding with either coding: or encoding: at the top of the file:

# encoding: UTF-8
# or
# coding: UTF-8

Must appear in the first comment section of the file.

frozen_string_literal

Introduced in Ruby 2.3, this makes all string literals in the file implicitly frozen—as if #freeze had been called—raising RuntimeError if you try to mutate them.

# frozen_string_literal: true

def test
  s = "hello world"
  s.object_id
end

p test  # => e.g., 260
p test  # => same object_id when reused by the VM

Notes:

• You can enable frozen literals globally via CLI (--enable=frozen-string-literal) and still override per-file with this comment.
• To force a mutable copy from a literal in a frozen-string file, use unary + or call .dup:

name = +"hello"   # mutable copy

• To explicitly freeze a literal, you can also use unary -:

key = -"api:v1"

shareable_constant_value

Experimental in Ruby 3.0+, this directive helps create constants that hold only immutable (Ractor-shareable) objects. It can take one of:

• none (default): no special treatment
• literal: constants assigned to literals are deeply frozen
• experimental_everywhere: all constant assignments become shareable (aggressive)
• experimental_copy: values are frozen and copied to avoid freezing original dynamic objects

It can be used multiple times in a file; it affects only subsequent constants and only in the current scope.

See Ruby docs for details on behavior and caveats.

warn_indent

Shows a warning when indentation is mismatched. The last warn_indent: in the file wins.

# warn_indent: true

def comments
  end
# => warning: mismatched indentations at 'end' with 'def' at 3

Running Ruby with -w (warnings) can also surface indentation issues; setting the directive to false suppresses these warnings.

Wrap-up

• Place magic comments at the very top (after an optional shebang).
• Use encoding for non-UTF-8 files (rare today), frozen_string_literal for performance & safety, shareable_constant_value when working with Ractors/immutability, and warn_indent to catch formatting issues quickly.

You might also like

• Module Functions in Ruby
• Working with Files in Ruby