Installation

This page covers what Loofah needs, how to install it, and how to confirm that the HTML5 parser is available on your platform. That last point matters: Loofah's recommended entry points (Loofah.html5_fragment and friends) only work when your Nokogiri build supports HTML5.

Requirements

The gemspec (loofah.gemspec) declares:

Requirement	Version
Ruby	`>= 2.5.0`
`nokogiri`	`>= 1.12.0`
`crass`	`~> 1.0.2` (CSS tokenizer used to sanitize `style` attributes)

Note: The README's "Requirements" section still says Nokogiri >= 1.5.9 and Ruby >= 2.5. The gemspec is what RubyGems enforces, so Nokogiri 1.12.0 is the real minimum.

The project's CI tests Ruby 2.5 through 3.4, Ruby head, TruffleRuby head, and JRuby 9.4, 10.0, and head.

HTML5 support

HTML5 parsing is optional and depends on Nokogiri. Loofah enables it only when both of these are true (see Loofah.html5_support? in lib/loofah.rb):

Nokogiri::VERSION is greater than 1.14.0, and
Nokogiri.uses_gumbo? returns true (Nokogiri was built with its Gumbo HTML5 parser).

In practice this means:

Platform	HTML5 available?
CRuby (MRI) with Nokogiri newer than 1.14.0	Yes
CRuby with Nokogiri 1.12.x, 1.13.x, or exactly 1.14.0	No
JRuby (any Nokogiri version)	No, Nokogiri's Java implementation has no Gumbo parser

Note: The README says HTML5 is unavailable "with versions of Nokogiri < 1.14.0", but the code compares with a strict >, so Nokogiri 1.14.0 itself is also excluded. Use 1.14.1 or later.

When HTML5 support is missing, the Loofah::HTML5::Document and Loofah::HTML5::DocumentFragment classes are not defined at all, and every html5_* method raises:

NotImplementedError: Loofah::HTML5 is not supported by your version of Nokogiri

Install with Bundler

Add the gem to your Gemfile:

gem "loofah"

Then install:

bundle install

If you use Rails, Loofah is very likely already in your bundle as a dependency of rails-html-sanitizer. Check with:

bundle info loofah

Install with RubyGems

gem install loofah

Requiring the Library

require "loofah"

This loads the parsers, the scrubbers, and the safelist. The Rails-style view helpers are not loaded automatically; require them separately if you need them:

require "loofah/helpers"

Verifying the Installation

Run a one-liner that prints the version and whether HTML5 is available:

ruby -rloofah -e 'puts Loofah::VERSION; puts Loofah.html5_support?'

On CRuby with a recent Nokogiri, the output is similar to:

2.25.2
true

Then try a scrub:

ruby -rloofah -e 'puts Loofah.scrub_html4_fragment("<b>hi</b><script>x</script>", :prune)'

<b>hi</b>

This uses the HTML4 parser so it works on every platform. Replace html4 with html5 to confirm the HTML5 path.

Troubleshooting Installation

HTML5 methods raise NotImplementedError

Your Nokogiri is 1.14.0 or older, or you are on JRuby. Upgrade Nokogiri (bundle update nokogiri) on CRuby, or use the html4_* methods on JRuby. See Documents and Fragments for the differences.

NameError for Loofah::HTML5::Document

Same cause as above: the HTML5 classes are only defined when HTML5 is supported. Guard code that must run everywhere with if Loofah.html5_support?.

NameError for Loofah::Helpers

The helpers are opt-in. Add require "loofah/helpers".

Bundler cannot resolve nokogiri or crass

Loofah needs Nokogiri 1.12.0 or newer and a crass 1.0.x release of at least 1.0.2. Older lockfiles that pin Nokogiri below 1.12 must be updated.

Upgrading

Read the CHANGELOG before upgrading. Loofah follows a conservative release style, but security releases sometimes tighten what is allowed. For example, 2.25.2 removed the feed protocol from the allowed URI schemes and changed how data: URIs are parsed.