Guide · Open source

How to use Liquid: install the Ruby gem and render templates

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Liquid is a template engine that fills placeholders in text or HTML with real data, such as a product name or price. It is written in Ruby and installed as a gem, and it is designed so that templates can be written by non-programmers or untrusted users because they cannot run arbitrary code on the server. This guide shows you how to install it, render your first template, and use environments, error modes and strict checks.

LiquidShopify/liquid · ★ 11.9k · MIT Install options & downloads

Quick start

1Check for Ruby. Liquid is a Ruby gem, so confirm your project runs on Ruby before you start.
2Add the gem. Add gem 'liquid' to your Gemfile and install your gems as you normally do.
3Parse a template. Call Liquid::Template.parse with your template string to compile it once.
4Render with data. Call render with a hash of local variables, such as 'name' => 'tobi'.
5Turn on strict checks. Set an error mode such as :strict or :warn on new templates to catch invalid syntax early.
6Isolate customisations. Use Liquid::Environment.build to register custom tags and filters for each context.

What does a Liquid template look like?

A Liquid template is ordinary HTML with placeholders and simple control tags added. Values are written inside double curly braces, and loops use percent-brace tags. Filters, such as price or paragraph, transform a value before it is output.

Liquid was built to have simple, readable markup, and it is intended to be safe for users to edit.

<ul id="products">
  {% for product in products %}
    <li>
      <h2>{{ product.name }}</h2>
      Only {{ product.price | price }}

      {{ product.description | prettyprint | paragraph }}
    </li>
  {% endfor %}
</ul>

Install Liquid in a Ruby project

Liquid is installed as a Ruby gem. You need Ruby, then add the gem to your Gemfile. The README documents only this Ruby gem route, so this guide does not cover other languages.

Make sure Ruby is installed.
Add the gem line to your Gemfile.
Install your project's gems with Bundler as you normally would.

gem 'liquid'

Parse and render your first template

Liquid's basic API is built around the Liquid::Template class. Parsing compiles the template once, and rendering passes in a hash of local variables. Because compiling is separate from rendering, you can parse once and render many times with different data.

@template = Liquid::Template.parse("hi {{name}}") # Parses and compiles the template
@template.render('name' => 'tobi')                # => "hi tobi"

Use environments to isolate custom tags and filters

An environment is a scoped set of custom tags, filters and configuration. Liquid recommends environments over global overrides, because custom tags and filters then only apply where they are needed and do not clash with each other. For smaller projects, a global environment is available as Liquid::Environment.default.

Build a separate environment for each context, such as storefront pages or email templates.
Pass the environment to parse with the environment option.

user_environment = Liquid::Environment.build do |environment|
  environment.register_tag("renderobj", RenderObjTag)
end

Liquid::Template.parse(<<~LIQUID, environment: user_environment)
  {% renderobj src: "path/to/model.obj" %}
LIQUID

Choose an error mode

By default the parser is lax and accepts almost anything, which can make bugs hard to find. Liquid offers stricter error modes that raise a SyntaxError for invalid syntax. The README recommends enabling strict or warn mode on new apps, and using strict modes in template editors of existing apps to give editors better error messages.

You can set the mode globally on the default environment, or pass error_mode to parse to change it for a single template.

strict2: raises a SyntaxError for invalid syntax in all tags.
strict: raises a SyntaxError for invalid syntax in some tags.
warn: adds strict errors to template.errors and continues as normal.
lax: the default mode, which accepts almost anything.

Liquid::Environment.default.error_mode = :strict2
Liquid::Template.parse(source, error_mode: :strict)

Catch undefined variables and filters

By default, rendering does not tell you when a variable or filter is missing. Pass strict_variables: true and/or strict_filters: true to render to collect these problems in the template's errors array. Use render! instead if you want to raise on the first error.

When a variable is undefined it renders as nil, and when any filter in a chain is undefined the whole expression renders as nil.

strict_variables: true collects undefined variable errors.
strict_filters: true collects undefined filter errors.
render! raises on the first error.

template = Liquid::Template.parse("{{x}} {{y}} {{z.a}} {{z.b}}")
template.render({ 'x' => 1, 'z' => { 'a' => 2 } }, { strict_variables: true })
#=> '1  2 ' # when a variable is undefined, it's rendered as nil
template.errors

Understand resource limits

The README describes render_score_limit and cumulative_render_score_limit, which count each item visited by integer-range for and tablerow loops, including loops with empty bodies. render_length_limit only bounds generated output and does not by itself limit CPU work for output-free loops, so it is not a complete guard on its own.

What people use it for

Letting customers edit the appearance of a Ruby app without running their code on the server.
Rendering templates stored in a database.
Using one template format for both HTML pages and emails.
Showing product names and prices inside a product listing template.

Frequently asked questions

Is Liquid free to use?

Liquid is released under the MIT licence. The source does not mention any pricing.

What do I need to install Liquid?

You need Ruby. Liquid is installed by adding gem 'liquid' to your Gemfile, as documented in the README.

How do I install Liquid?

Add gem 'liquid' to your Gemfile and install your project's gems. The README documents only this package-manager method.

Can I use Liquid with Python or JavaScript?

The README only documents a Ruby gem, so this guide does not cover other languages. Check the project's homepage and documentation for any other options.

Why is my Liquid template not showing errors?

By default the parser is lax and renders missing variables as nil. Use error_mode :strict or :warn, and pass strict_variables: true to render to collect undefined variable and filter errors.

How does Liquid compare to Mustache, Handlebars or ERB?

Liquid is intentionally limited and designed to be safe for user-edited templates, since templates cannot run arbitrary code. Mustache, Handlebars and ERB are comparable projects, but this source does not compare their features in detail.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Liquid suits Ruby developers who want to let customers or editors change how an app looks without running untrusted code on the server. It is a poor fit if you need a full general-purpose scripting language inside templates, or if your project does not use Ruby.

Install options & downloads