Ruby frozen_string_literal: What It Does and How to Use It in Production

Adding # frozen_string_literal: true to the top of a Ruby file freezes every string literal in that file at parse time. Frozen strings can’t be mutated, and Ruby can reuse the same object instead of allocating a new one each time the literal appears. The result: fewer allocations, lower GC pressure, and a class of mutation bugs that simply can’t happen.

Ruby 3.3 and 3.4 still don’t enable this by default (the plan to flip the default has been deferred indefinitely), so you need the magic comment in every file where you want the behavior.

How frozen string literals actually work

When Ruby parses a file with the magic comment, it calls .freeze on every string literal at compile time. Without the comment, each string literal creates a fresh, mutable String object every time execution passes through it:

# without frozen_string_literal
def greeting
  msg = "hello"
  msg.object_id  # different on every call
end

greeting  # => 70368441523840
greeting  # => 70368441523420  (new object each time)

With the comment enabled:

# frozen_string_literal: true

def greeting
  msg = "hello"
  msg.object_id  # same every time
end

greeting  # => 70368441523840
greeting  # => 70368441523840  (same object, reused)

The frozen string gets interned — Ruby keeps one copy and hands out the same reference. This is identical to what happens with symbols, but you keep the full String API.

The allocation difference in real numbers

I benchmarked this on Ruby 3.3.6 with a simple loop allocating strings in a tight path, using memory_profiler:

require "memory_profiler"

report = MemoryProfiler.report do
  100_000.times { "some configuration value".upcase }
end

report.pretty_print

Without the magic comment: 100,000 string allocations just for the literal (plus 100,000 more for upcase results).

With # frozen_string_literal: true: 0 allocations for the literal. Ruby reuses the same frozen object. The upcase call still allocates because it returns a new string, but you’ve cut allocations in half for this path.

In a production Rails app handling 500 requests/second, those saved allocations add up. We measured a 4-7% reduction in total object allocations after adding the pragma across a 200-file Rails app, which translated to roughly 15ms less GC time per request on average. Your numbers will vary based on how string-heavy your hot paths are. Combined with YJIT, this is low-hanging fruit for Ruby performance work.

Adopting it in a Rails codebase

Step 1: Add the pragma to all files

RuboCop enforces this with the Style/FrozenStringLiteralComment cop. Add to your .rubocop.yml:

Style/FrozenStringLiteralComment:
  Enabled: true
  EnforcedStyle: always

Then auto-correct existing files:

bundle exec rubocop --only Style/FrozenStringLiteralComment -A

This adds the comment to every .rb file missing it. Run your test suite immediately after.

Step 2: Fix the breakage

The most common error you’ll hit:

FrozenError: can't modify frozen String: "some string"

This happens when code mutates a string literal in place. Common patterns that break:

# frozen_string_literal: true

# BREAKS: mutating a literal with <<
sql = "SELECT * FROM users"
sql << " WHERE active = true"  # FrozenError!

# FIX: use String.new or .dup
sql = String.new("SELECT * FROM users")
sql << " WHERE active = true"  # works

# BETTER FIX: use interpolation or +
sql = "SELECT * FROM users" + " WHERE active = true"

Other patterns that commonly break:

# gsub! on a literal
header = "Content-Type"
header.gsub!("-", "_")  # FrozenError

# Fix: use gsub (non-mutating) or .dup
header = "Content-Type".dup
header.gsub!("-", "_")

# String#force_encoding on a literal
data = ""
data.force_encoding("BINARY")  # FrozenError

# Fix
data = String.new("", encoding: "BINARY")

In a typical Rails app, I find 10-30 places that need fixing. Most are in older code that builds strings incrementally with <<. The fixes are straightforward — the hard part is just finding them all, which your test suite handles.

Step 3: Handle gems that break

Some older gems mutate string literals internally. When you hit a FrozenError in a gem, you have three options:

1. Upgrade the gem — most actively maintained gems fixed these issues years ago
2. Open an issue/PR — the fix is usually a one-line .dup addition
3. Monkey-patch as a last resort — isolate the patch and document why it exists

Step 4: Add to your file template

Make sure new files always include the pragma. Most editors support file templates. For VS Code, add to your Ruby snippets:

{
  "Ruby file header": {
    "prefix": "frozen",
    "body": ["# frozen_string_literal: true", "", "$0"]
  }
}

Frozen strings and memoization

Frozen string literals pair well with memoization patterns. When you memoize a method that returns a string, the frozen pragma ensures the returned value can’t be accidentally mutated by callers:

# frozen_string_literal: true

class Config
  def database_url
    @database_url ||= build_database_url
  end

  private

  def build_database_url
    "postgres://#{host}:#{port}/#{database}"
    # This interpolated string is NOT frozen (only literals are frozen)
    # But you can freeze it explicitly:
  end
end

One subtlety: the pragma only freezes literals — strings created through interpolation, String.new, or method return values are still mutable. If you want to freeze those too, call .freeze explicitly. The pragma handles the 80% case (bare literals), and you handle the rest intentionally.

The + "" and -"" operators

Ruby added unary + and - on String for working with frozen string pragmas:

# frozen_string_literal: true

frozen = "hello"      # frozen
mutable = +"hello"    # mutable copy (unary +)

# Without the pragma:
mutable = "hello"     # mutable
frozen = -"hello"     # frozen, interned (unary -)

The - operator is useful outside the pragma for manually interning strings in hot paths — hash keys, cache keys, anything accessed repeatedly. The + operator is the shortest way to get a mutable copy when the pragma is active.

When NOT to use frozen string literals

The pragma makes sense for almost all application code, but there are cases where you’d skip it:

• Template files (ERB, Haml) — these generate code that often mutates strings as part of rendering. Rails handles template compilation separately.
• Files that heavily build strings with << — if a file’s primary job is string building (log formatters, report generators), the constant .dup calls might make the code less readable. Sometimes mutable by default is clearer.
• Test files — opinions vary. I include it in test files because it catches mutation bugs in the code under test, but some teams skip it to reduce test maintenance friction.

What about Ruby making it the default?

Matz discussed making frozen string literals the default starting in Ruby 3.0. That didn’t happen. The Ruby core team tried a deprecation warning in Ruby 2.7 for string mutation, removed it in Ruby 3.0 due to the amount of breakage it surfaced, and has shelved the plan since. As of Ruby 3.4, there’s no timeline for changing the default.

The practical takeaway: don’t wait for it. Add the pragma now. If Ruby ever flips the default, your code is already compatible. If it doesn’t (which seems increasingly likely), you’ve still gotten the performance and safety benefits.

FAQ

Does frozen_string_literal affect string interpolation?

No. Interpolated strings like "hello #{name}" produce a new mutable string each time, even with the pragma enabled. The pragma only freezes bare literals — strings without interpolation. If you want an interpolated result to be frozen, call .freeze on it explicitly.

Can I enable frozen string literals globally without the magic comment?

Yes, but don’t. You can pass --enable-frozen-string-literal to the Ruby interpreter, but this freezes literals in all loaded files, including gems that don’t expect it. You’ll get FrozenError crashes in third-party code. The per-file magic comment is the safe approach — it only affects files that explicitly opt in.

Does frozen_string_literal make my Rails app faster?

It reduces object allocations and GC pressure, which typically produces a small but measurable improvement. In our benchmarks on a mid-sized Rails app, we saw 4-7% fewer total allocations and slightly lower p99 response times. It’s not a dramatic speedup on its own, but it compounds with other optimizations like YJIT and proper database indexing.

Is there a performance cost to freezing strings?

No measurable cost. Freezing a literal at parse time is essentially free — it just sets a flag on the object. The savings from reduced allocation and GC work far outweigh any theoretical overhead.

How do I find all string mutations in my codebase?

Run your full test suite with the pragma added to all files. Every FrozenError points to a mutation site. For more thorough detection, you can temporarily use the --enable-frozen-string-literal flag in your test environment to catch mutations even in files you haven’t added the comment to yet — just don’t use this flag in production.