Liquidpy is a Python port of the Liquid template engine, built on top of Jinja2, that renders Liquid templates with four compatibility modes.
What is Liquidpy?
Liquidpy is a Python library that implements the Liquid template language (originally created by Shopify) using Jinja2 as its underlying engine. It accepts Liquid template strings or file paths as input and outputs rendered text by injecting Python variables, filters, and tags. The library is developed by pwwang and distributed on PyPI with the package name liquidpy.
Key Features
- Four modes — standard (default), Jekyll, Shopify, and wild; each mode changes available tags and filters to match the target platform's Liquid dialect.
- Jinja2 environment support — use an existing Jinja2 Environment with custom loaders and extensions via
Liquid.from_env. - Python in templates — wild mode enables a
pythonblock tag so you can execute arbitrary Python code inside a template, such asfrom os import path. - File and string loading — load templates from file paths or directly from strings by passing
from_file=Falseto the constructor. - Configurable defaults — set library-wide defaults for
from_fileandmodein thedefaultsmodule once, then constructLiquidinstances without repeating those options. - Interactive playground — test templates in the browser via a PyScript-powered playground at pwwang.github.io/liquidpy/playground.
Who is it for?
- Python developers migrating from Jinja2 to Liquid — use liquidpy as a drop-in renderer that reuses an existing Jinja2 Environment for loaders and extensions.
- Jekyll or Shopify theme developers — run templates in the matching mode to catch syntax differences before deploying to those platforms.
- Library maintainers — embed a Liquid-compatible template engine in Python tools by installing liquidpy from PyPI.
What can you do with Liquidpy?
- Render a simple variable: create
Liquid('{{a}}', from_file=False)and callrender(a=1)to get the string '1'. - Use a custom Jinja2 environment: pass an
Environment(loader=FileSystemLoader('./'))toLiquid.from_envand load templates from disk with your existing setup. - Execute Python logic in templates: with
mode='wild', embed apythonblock that imports modules and uses the results in the output, like joining path components. - Switch compatibility modes per project: choose standard, Jekyll, Shopify, or wild to match the Liquid dialect you are targeting.
How does Liquidpy work?
Install with pip install -U liquidpy, then import Liquid and instantiate it with a template string or file path. The render method accepts keyword arguments that become template variables; if a Jinja2 Environment is provided, Liquidpy renders through it. Changing defaults via the defaults module lets you set from_file and mode globally so they do not need to be passed each time.
FAQ
Is Liquidpy free?
Yes, liquidpy is an open-source Python package distributed on PyPI; there is no paid tier or licensing fee mentioned in the documentation.
What Liquid modes does Liquidpy support?
It supports four modes: standard (the default), Jekyll, Shopify, and wild. Wild mode allows raw Python code inside template tags, while the other three match the public Liquid dialects from Shopify's ecosystem.
Can I use Liquidpy with an existing Jinja2 environment?
Yes, use Liquid.from_env and pass a jinja2.Environment instance; Liquidpy will render Liquid templates using that environment's loader and extensions.
How do I load a template from a file?
Pass the file path to Liquid, for example Liquid('/path/to/template.html'), and the library reads the file. Alternatively, set defaults.FROM_FILE = True so all template paths are treated as file paths by default.
Does Liquidpy have a playground?
Yes, there is a browser-based playground powered by PyScript at https://pwwang.github.io/liquidpy/playground where you can test Liquid templates online.
