haml-rails: the gem that makes Rails generate Haml instead of ERB

What the gem does: three effects, all of them about generators

haml-rails provides Haml generators for Rails 5, 6, 7 and 8, and the README explains the design in one plainly worded sentence. It enables Haml as the templating engine so that you do not have to screw around in your own application.rb when the Gemfile already clearly indicated what templating engine you have installed. The gem is added to the Gemfile, and the project then lists three consequences. Any time you generate a resource, a view or a mailer, you get Haml templates instead of ERB ones. When the Rails application loads, Haml is loaded and initialised automatically. And Haml templates are respected by the view template cache digestor. That third point is the one that separates this from a partial implementation, because a template engine that the cache digestor does not understand will not invalidate correctly in development.

gem "haml-rails"

Why the Gemfile hook rather than a manual engine setting

The design decision here is about where the configuration lives, and it is worth stating plainly because it cuts both ways. In a conventional setup, the template engine is set in an initializer or in application.rb, which means the Gemfile and the application configuration can disagree, and a developer reading the Gemfile does not learn the whole story. Here the Gemfile is the single source of truth, because the generator templates and the engine registration ship in the same gem and activate together. The result is that adding one line to the Gemfile changes the output of every generator you run from that point on. The trade-off is that the engine choice becomes implicit and somewhat invisible, which is convenient for a team that has already decided and mildly surprising for a developer who opens the repository and finds no mention of Haml in application.rb. The README's own framing, with the hurrah at the end, is not neutral about which of the two positions the author prefers.

Converting the application layout, and the manual step that follows

The first migration path handles the single file that matters most, the application layout. The command is rails generate haml:application_layout convert, and it converts app/views/layouts/application.html.erb to app/views/layouts/application.html.haml. It requires the html2haml gem, which is installed with gem install html2haml. There is then a step the README is explicit about. After the application layout file is converted successfully, you must delete app/views/layouts/application.html.erb, so that Rails starts using the .haml file instead. That is a small but genuine hazard, because the two files coexist perfectly well and Rails will keep rendering the ERB one, so a migration that appears to succeed can leave the application still serving the old template. The manual deletion is the step that makes the switch real, and it is the kind of instruction that is easy to read past.

gem install html2haml
rails generate haml:application_layout convert

erb2haml: converting the whole view set, and the question it asks

For a full migration the command is rails haml:erb2haml, and it converts all of your .erb views into .haml. Two behaviours of the task are worth knowing. If you already have .haml files for one or more of the .erb files, the task gives you the option of either replacing those .haml files or leaving them in place, so a partial migration is safe to re-run. And when the task completes you get the option of deleting the original .erb files, with a strong recommendation: unless you are under version control, decline this option. The reason is given for the scripted case too. If you are running in a script you can use an environment variable to answer the question, and setting HAML_RAILS_DELETE_ERB=true makes the task non interactive and deletes the originals, while setting it to false also suppresses the prompt and leaves the .erb files intact. So the same task is safe or destructive depending on one variable, and the default is the cautious path.

rails haml:erb2haml
HAML_RAILS_DELETE_ERB=true rails haml:erb2haml

Version pinning: Rails 4 and Rails 3 each have their own line

The Older versions of Rails section is short and it removes an obvious source of confusion. The current version of haml-rails requires Rails 5.1 or later. Version 1.0.0 is the last version to support Rails 4, and to use it you add the line gem "haml-rails", "~> 1.0.0" to your Gemfile. For Rails 3, use version 0.4, added as gem "haml-rails", "~> 0.4.0". So there are three supported lines in the gem's history and the constraint you write picks one. The current line covers the four Rails majors the README names, 5, 6, 7 and 8, and the older lines exist for applications that have not moved. A team still on Rails 4 is not stuck with an unmaintained Haml, it just has to pin an older gem version, which is the normal mechanism in the Ruby ecosystem.

The repository shows a small, focused gem with a real test suite

The top level of the repository is compact. There is a haml-rails.gemspec, a Gemfile, a Rakefile, a lib/ directory holding the code, a test/ directory, a CHANGELOG.md, a LICENSE file and the README, plus a .github/ directory with the Ruby workflow that produces the badge at the top of the README. The gem is published to RubyGems, with the version badge pointing at the rubygems.org gem page. There are no GitHub releases, which is the normal pattern for a gem, since the release artefact is the gem itself rather than a tagged tarball. The last push to the repository was on 2026-09-05, and the repository is not archived. The size of the codebase matches the size of the feature set, and the presence of a test directory and a Rakefile indicates the generators are exercised rather than assumed.

Provenance and licence: borrowed generators, dual licensing

The Contributors section gives the lineage, which is worth reading because it explains the shape of the code. The Haml generators originally came from rails3-generators, and were written by José Valim, André Arko, Paul Barry, Anuj Dutta, Louis T and Chris Rhoden, with the tests originally written by Louis T. The repository is under the haml organisation, and the primary language is Ruby. The licence is stated in a way that is unusual and worth quoting rather than paraphrasing: Ruby license or MIT license, take your pick. That dual offer matters more than it might look, because the two licences carry different terms, so a company with a policy about which licence texts it accepts should pick the one its policy names. The README does not go further than that sentence, so anyone with a specific compliance question would have to read the LICENSE file itself.

Editorial conclusion

haml-rails suits a Rails team that has already decided to use Haml and wants the framework to stop generating ERB without editing application.rb by hand, and that has a large existing ERB codebase to migrate. It is the wrong choice for a new Rails application, because choosing a template engine is a decision the application should make explicitly rather than one made by a gem in the Gemfile, and a poor fit if you need features from newer Haml that this gem does not yet track. Before adopting it, confirm your Rails version is 5.1 or newer, since version 1.0.0 is the last to support Rails 4 and version 0.4 is the one for Rails 3, and read the licence note, because the project is offered under either the Ruby licence or MIT.

Frequently asked questions

Official sources

1. haml/haml-rails on GitHub
2. Issues
3. License: MIT
4. README