Python Liquid

2.1.0 · active · verified Sat Apr 11

Python Liquid is a Python engine for Liquid, the safe, customer-facing template language, currently at version 2.1.0. It closely follows Shopify/Liquid's design and test suite, providing a robust and secure templating solution for web applications. While there isn't a fixed release cadence, the project is actively maintained with regular updates.

Warnings

breaking Upgrading from Python Liquid 1.x to 2.x may involve breaking API changes. The project maintains separate documentation archives for older major versions, indicating significant shifts.
Fix: Refer to the archived documentation for 1.x and the current documentation for 2.x to identify specific API changes and migration paths. Thoroughly test your application after upgrading.
gotcha For all but the simplest one-off string renderings, using `liquid.Environment` with a template loader is more efficient and provides better configurability than repeatedly creating `liquid.Template` instances directly.
Fix: Initialize a single `Environment` instance for your application and use its `get_template()` or `from_string()` methods to load and render templates.
gotcha Liquid's default behavior for whitespace in templates can lead to unwanted blank lines or spaces in the rendered output.
Fix: Utilize whitespace control characters (`-` within `{%` or `}}` tags, e.g., `{%-` or `-%}`) to strip leading or trailing whitespace around tags and output, as described in the Liquid syntax documentation.
gotcha Liquid is designed as a secure, non-evaluating template language. It does not allow arbitrary Python code execution within templates. Attempting to implement complex application logic directly in Liquid templates might be cumbersome or impossible.
Fix: Keep business logic in your Python application code. Use Liquid templates solely for presentation and data display. Pre-process data in Python before passing it to the Liquid template for rendering.

Install

pip install python-liquid Install with pip

Imports

render
```
from liquid import render
```
parse
```
from liquid import parse
```
Template
```
from liquid import Template
```
Environment
```
from liquid import Environment
```
FileSystemLoader
```
from liquid import FileSystemLoader
```

Quickstart

The simplest way to render a template string is using the package-level `render()` function. For applications requiring configuration, template loading from files, or better performance, it's recommended to configure an `Environment` instance. This example demonstrates using `Environment` with a `FileSystemLoader` to render a template from a file, passing variables and accessing globals.

from liquid import Environment, FileSystemLoader
import os

# For a simple template string, use render() or parse():
# from liquid import render
# print(render("Hello, {{ you }}!", you="World"))

# For more complex applications, an Environment is recommended.
# This example assumes a 'templates' directory with 'index.liquid'.

# Create a dummy templates directory and file for demonstration
os.makedirs("templates", exist_ok=True)
with open("templates/index.liquid", "w") as f:
    f.write("Hello, {{ name }}! From {{ app_name }}. Today is {{ date | date: '%Y-%m-%d' }}.")

env = Environment(
    loader=FileSystemLoader("templates/"),
    globals={
        "app_name": os.environ.get('LIQUID_APP_NAME', 'Default App') # Example with env var
    }
)

template = env.get_template("index.liquid")
output = template.render(name="Liquid User", date="2026-04-11")
print(output)

# Clean up dummy files/directory
os.remove("templates/index.liquid")
os.rmdir("templates")

view raw JSON →