Mako Templating Library

1.3.10 verified Tue May 12 auth: no python install: verified quickstart: stale

Mako is a hyperfast and lightweight templating language for Python, designed to be both powerful and easy to use. The current version is 1.3.10, released on March 28, 2026. Mako follows a regular release cadence, with updates addressing bugs and improvements.

pip install mako

Common errors

error NameError: name 'some_variable' is not defined ↓

cause A variable is referenced in the Mako template that was not passed into the `render()` context, or `strict_undefined=True` is enabled and a variable is missing.

fix

Ensure all variables used in the template are passed in the dictionary to template.render(). For clearer debugging, initialize Template or TemplateLookup with strict_undefined=True to get specific NameError messages including the variable name.

error ModuleNotFoundError: No module named 'mako' ↓

cause The Mako library is not installed in the Python environment being used, or the Python interpreter cannot find it in its `sys.path`.

fix

Install Mako using pip: pip install mako. Verify that the correct Python environment's pip is used for installation.

error SyntaxError: invalid syntax ↓

cause There is a Python syntax error within a `<% ... %>` block in the Mako template, or Mako's special tags (`<%`, `%>`, `${}`) are used incorrectly or unescaped in content that Mako tries to parse as code.

fix

Carefully review the Python code within template blocks for syntax correctness (e.g., missing colons, incorrect indentation). If Mako tags are intended as literal text, escape them (e.g., write <%% for <%).

error TypeError: 'Undefined' object is not callable ↓

cause An undefined variable, represented by Mako's `UNDEFINED` object when `strict_undefined=False`, is treated as if it were a callable function or an object with attributes.

fix

Explicitly pass the expected variable to the template's rendering context or check for its existence (e.g., if var is not UNDEFINED:) before attempting to call methods or access attributes. Alternatively, initialize Template or TemplateLookup with strict_undefined=True to raise a NameError for missing variables sooner.

error mako.exceptions.TopLevelLookupException: Cant locate template for uri %r ↓

cause Mako's `TemplateLookup` cannot find an included (`<%include>`) or inherited (`<%inherit>`) template file at the specified URI within its configured `directories`.

fix

Verify that the directories argument passed to TemplateLookup correctly points to the location of your template files and that the URI used in <%include> or <%inherit> tags is correct and relative to those directories.

Warnings

breaking Mako now requires Python >= 3.7, removing support for Python 2 and Python 3.6. ↓

fix Upgrade your Python environment to version 3.7 or later.

deprecated The use of 'import="*"' in <%namespace> is known to decrease performance and will be fixed in a future release. ↓

fix Avoid using 'import="*"' in <%namespace> tags to maintain optimal performance.

breaking Mako failed to locate a template file, resulting in a TopLevelLookupException. This typically occurs when the template file does not exist at the specified path or the template lookup directories are not configured correctly. ↓

fix Ensure the template file exists and that the mako.lookup.TemplateLookup object is initialized with the correct 'directories' parameter pointing to the template's location.

breaking Mako raises `TopLevelLookupException` when a template file specified cannot be found in the configured lookup directories. ↓

fix Ensure the template file exists at the specified path and that Mako's `TemplateLookup` object is correctly initialized with the directory containing the template.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.18s 18.5M

3.10 slim (glibc) - - 0.17s 19M

3.11 alpine (musl) - - 0.23s 20.5M

3.11 slim (glibc) - - 0.19s 21M

3.12 alpine (musl) - - 0.20s 12.4M

3.12 slim (glibc) - - 0.20s 13M

3.13 alpine (musl) - - 0.15s 12.0M

3.13 slim (glibc) - - 0.16s 13M

3.9 alpine (musl) - - 0.10s 18.0M

3.9 slim (glibc) - - 0.09s 19M

Imports

Template
```
from mako.template import Template
```
Ensure correct import path to access the Template class.
TemplateLookup
```
from mako.lookup import TemplateLookup
```
Ensure correct import path to access the TemplateLookup class.

Quickstart stale last tested: 2026-04-23

This example demonstrates how to set up a template lookup, load a template, and render it with variables using Mako.

from mako.template import Template
from mako.lookup import TemplateLookup

# Set up template lookup
mylookup = TemplateLookup(directories=['/path/to/templates'])

# Load a template
mytemplate = mylookup.get_template('mytemplate.html')

# Render the template with variables
output = mytemplate.render(variable1='value1', variable2='value2')

print(output)