Install & Compatibility
Where this runs
tested against v1.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 24.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.0s · import 0.000s · 25MB
27MB installed
● package 27MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
includeme
✓ config.include('pyramid_mako')
Registers the Mako renderer with your Pyramid application's Configurator.
render
✓ from pyramid.renderers import render
Used for direct rendering of a template within a view callable.
add_mako_renderer
✓ config.add_mako_renderer('.html', settings_prefix='mako.')
Configurator directive to register additional Mako renderers for different file extensions or with specific settings.
This quickstart demonstrates how to set up a basic Pyramid application using `pyramid_mako`. It shows how to include `pyramid_mako` in your configuration, define a template directory using `mako.directories`, and render a Mako template from a Pyramid view. Views that use a renderer should return a dictionary, whose keys become top-level variables in the template. The example provides a small, self-contained Pyramid application. Note that for real-world applications, you'd typically use a `development.ini` file and a proper project structure created by a Pyramid cookiecutter.
import os
from wsgiref.simple_server import make_server
from pyramid.config import Configurator
from pyramid.response import Response
from pyramid.view import view_config
# --- myapp/__init__.py ---
@view_config(route_name='home', renderer='templates/home.mako')
def home_view(request):
name = request.matchdict.get('name', 'World')
return {'project': 'Pyramid Mako App', 'user_name': name}
def main(global_config, **settings):
with Configurator(settings=settings) as config:
config.include('pyramid_mako')
# Configure mako.directories for template lookup if using relative paths
# For this example, 'templates' is relative to the current package.
# If using asset specs like 'mypackage:templates', no mako.directories needed for that specific template.
config.add_settings({'mako.directories': 'myapp:templates'})
config.add_route('home', '/howdy/{name}')
config.add_route('root', '/')
config.scan('.') # Scan current package for @view_config decorators
return config.make_wsgi_app()
# To run: Save this as myapp/__init__.py
# Create myapp/templates/home.mako:
# <h1>Hello, ${user_name} from ${project}!</h1>
# From your project root (one level above 'myapp'), run:
# pserve development.ini (assuming development.ini is configured to point to myapp.main)
# Or create a minimal development.ini:
# [app:main]
# use = egg:myapp#main
#
# [server:main]
# use = egg:waitress#main
# host = 0.0.0.0
# port = 6543
#
# [loggers]
# keys = root, myapp
#
# [handlers]
# keys = console
#
# [formatters]
# keys = generic
#
# [logger_root]
# level = INFO
# handlers = console
#
# [logger_myapp]
# level = DEBUG
# handlers = console
# qualname = myapp
#
# [handler_console]
# class = StreamHandler
# args = (sys.stderr,)
# level = NOTSET
# formatter = generic
#
# [formatter_generic]
# format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
if __name__ == '__main__':
# This block is typically replaced by 'pserve development.ini'
# For a truly minimal runnable example without an .ini file or folder structure:
class RootView:
def __init__(self, request):
self.request = request
@view_config(route_name='hello', renderer='string:<h1>Hello, ${user_name}!</h1>')
def hello(self):
return {'user_name': 'Anonymous'}
with Configurator() as config:
config.include('pyramid_mako')
config.add_route('hello', '/')
config.add_view(RootView, attr='hello')
app = config.make_wsgi_app()
server = make_server('0.0.0.0', 6543, app)
print('Serving on http://0.0.0.0:6543')
server.serve_forever()
Debug
Known issues
breakingAs of Pyramid 1.5, Mako templating support was removed from the Pyramid core. Projects upgrading to Pyramid 1.5 or newer must explicitly install `pyramid_mako` and activate it via `config.include('pyramid_mako')` in their application's `__init__.py` (or similar configuration entry point). Failure to do so will result in `ValueError: No such renderer factory .mako`.fixInstall `pyramid_mako` via `pip install pyramid-mako` and add `config.include('pyramid_mako')` to your Pyramid application's `Configurator` setup. affects: Pyramid >= 1.5
deprecatedReturning a `('defname', dict)` tuple from a view using a Mako renderer is deprecated and will raise a `ValueError` in `pyramid_mako` 1.0+. This behavior was removed to standardize renderer usage.fixInstead of returning a tuple, specify the Mako `def` name directly in the renderer argument of your view configuration (e.g., `renderer='mypackage:templates/foo.mak#defname'`) and return only a dictionary from your view callable.
affects: pyramid-mako >= 1.0, Pyramid >= 1.5
gotchaSetting `mako.strict_undefined = true` in your Pyramid application settings can cause issues with the `pyramid_debugtoolbar` if its internal Mako templates contain unguarded placeholders that might be undefined in certain contexts.fixIf `pyramid_debugtoolbar` breaks, avoid using `mako.strict_undefined = true` or use it with caution, ensuring all variables in your templates (and any templates you inherit from) are explicitly defined or guarded with `if` statements.
affects: All versions
gotchaAs of Pyramid 1.4, spaces are no longer allowed in Mako template paths when rendering. Template paths containing spaces will lead to lookup failures.fixEnsure all Mako template file paths and directory names used in your Pyramid configuration and renderer specifications do not contain spaces.
affects: Pyramid >= 1.4
Errors
Common errors & fixes
pyramid.exceptions.ConfigurationError: Renderer factory for .mako is not registered. Perhaps you forgot to include('pyramid_mako')?
The pyramid_mako package was not included in the Pyramid application configuration, so Pyramid does not know how to handle renderer names ending with '.mako'.
fixAdd `config.include('pyramid_mako')` to your application's `__init__.py` file (or wherever your Pyramid application configuration is performed). mako.exceptions.TemplateLookupException: Cannot find template 'my_template.mako' (or similar)
The specified template file does not exist at the configured Mako template lookup paths (`mako.directories`), or the path/filename in the view code is incorrect.
fixEnsure the template file exists in one of the directories listed in `mako.directories` in your .ini file, and that the template name in your `renderer=` argument or `render_to_response` call is correct and matches the file system path relative to those directories.
NameError: name 'my_variable' is not defined (within a Mako traceback for a template file)
A variable referenced in the Mako template (`${my_variable}`) was not passed to the template context when rendering the template.
fixEnsure all variables used within the template are explicitly passed as keyword arguments to the renderer or as part of the dictionary returned by the view callable. For example, `return {'my_variable': 'some_value'}`. ImportError: cannot import name 'render_to_response' from 'pyramid_mako'
The `render_to_response` function, while used with Mako templates in Pyramid, is part of the core Pyramid rendering system, not directly provided by the `pyramid_mako` integration package.
fixImport `render_to_response` from `pyramid.renderers` instead: `from pyramid.renderers import render_to_response`.
mako.exceptions.SyntaxException: Undefined filter 'html' (or any other filter)
A Mako filter (e.g., `h`, `html`, `url`) is used in a template (`${my_var | html}`) but has not been defined, is misspelled, or `mako.default_filters` is misconfigured in the application's .ini file.
fixEnsure the filter name is correct. If using built-in Mako filters, verify `mako.default_filters` is correctly configured in your `.ini` file (e.g., `mako.default_filters = html_entities`).
Upgrade
Version history
1.1.0latest on PyPI · released Aug 18, 2019
Audit
Dependencies
pyramidrequiredPyramid is the web framework for which these bindings are created.
MakorequiredMako is the templating engine being integrated; pyramid-mako 1.1.0 requires mako >= 1.1.0.