{"id":3236,"library":"pyramid-mako","title":"Mako Template Bindings for Pyramid","description":"Pyramid_mako provides a set of bindings that integrate the Mako templating system with the Pyramid web framework. It enables Pyramid applications to render dynamic content using Mako templates, which compile into Python modules for optimal performance. The library is currently at version 1.1.0 and is actively maintained by the Pylons Project, receiving updates to ensure compatibility with newer Python versions and Pyramid releases.","status":"maintenance","version":"1.1.0","language":"python","source_language":"en","source_url":"https://github.com/Pylons/pyramid_mako","tags":["pyramid","mako","templating","web framework","pylons"],"install":[{"cmd":"pip install pyramid-mako","lang":"bash","label":"Install pyramid-mako"}],"dependencies":[{"reason":"Pyramid is the web framework for which these bindings are created.","package":"pyramid"},{"reason":"Mako is the templating engine being integrated; pyramid-mako 1.1.0 requires mako >= 1.1.0.","package":"Mako","optional":false}],"imports":[{"note":"Registers the Mako renderer with your Pyramid application's Configurator.","symbol":"includeme","correct":"config.include('pyramid_mako')"},{"note":"Used for direct rendering of a template within a view callable.","symbol":"render","correct":"from pyramid.renderers import render"},{"note":"Configurator directive to register additional Mako renderers for different file extensions or with specific settings.","symbol":"add_mako_renderer","correct":"config.add_mako_renderer('.html', settings_prefix='mako.')"}],"quickstart":{"code":"import os\nfrom wsgiref.simple_server import make_server\nfrom pyramid.config import Configurator\nfrom pyramid.response import Response\nfrom pyramid.view import view_config\n\n# --- myapp/__init__.py ---\n@view_config(route_name='home', renderer='templates/home.mako')\ndef home_view(request):\n    name = request.matchdict.get('name', 'World')\n    return {'project': 'Pyramid Mako App', 'user_name': name}\n\ndef main(global_config, **settings):\n    with Configurator(settings=settings) as config:\n        config.include('pyramid_mako')\n\n        # Configure mako.directories for template lookup if using relative paths\n        # For this example, 'templates' is relative to the current package.\n        # If using asset specs like 'mypackage:templates', no mako.directories needed for that specific template.\n        config.add_settings({'mako.directories': 'myapp:templates'})\n\n        config.add_route('home', '/howdy/{name}')\n        config.add_route('root', '/')\n        config.scan('.') # Scan current package for @view_config decorators\n    return config.make_wsgi_app()\n\n# To run: Save this as myapp/__init__.py\n# Create myapp/templates/home.mako:\n# <h1>Hello, ${user_name} from ${project}!</h1>\n# From your project root (one level above 'myapp'), run:\n# pserve development.ini (assuming development.ini is configured to point to myapp.main)\n# Or create a minimal development.ini:\n# [app:main]\n# use = egg:myapp#main\n# \n# [server:main]\n# use = egg:waitress#main\n# host = 0.0.0.0\n# port = 6543\n# \n# [loggers]\n# keys = root, myapp\n# \n# [handlers]\n# keys = console\n# \n# [formatters]\n# keys = generic\n# \n# [logger_root]\n# level = INFO\n# handlers = console\n# \n# [logger_myapp]\n# level = DEBUG\n# handlers = console\n# qualname = myapp\n# \n# [handler_console]\n# class = StreamHandler\n# args = (sys.stderr,)\n# level = NOTSET\n# formatter = generic\n# \n# [formatter_generic]\n# format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s\n\n\nif __name__ == '__main__':\n    # This block is typically replaced by 'pserve development.ini'\n    # For a truly minimal runnable example without an .ini file or folder structure:\n    class RootView:\n        def __init__(self, request):\n            self.request = request\n\n        @view_config(route_name='hello', renderer='string:<h1>Hello, ${user_name}!</h1>')\n        def hello(self):\n            return {'user_name': 'Anonymous'}\n\n    with Configurator() as config:\n        config.include('pyramid_mako')\n        config.add_route('hello', '/')\n        config.add_view(RootView, attr='hello')\n        app = config.make_wsgi_app()\n\n    server = make_server('0.0.0.0', 6543, app)\n    print('Serving on http://0.0.0.0:6543')\n    server.serve_forever()","lang":"python","description":"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."},"warnings":[{"fix":"Install `pyramid_mako` via `pip install pyramid-mako` and add `config.include('pyramid_mako')` to your Pyramid application's `Configurator` setup.","message":"As 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`.","severity":"breaking","affected_versions":"Pyramid >= 1.5"},{"fix":"Instead 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.","message":"Returning 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.","severity":"deprecated","affected_versions":"pyramid-mako >= 1.0, Pyramid >= 1.5"},{"fix":"If `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.","message":"Setting `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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure all Mako template file paths and directory names used in your Pyramid configuration and renderer specifications do not contain spaces.","message":"As of Pyramid 1.4, spaces are no longer allowed in Mako template paths when rendering. Template paths containing spaces will lead to lookup failures.","severity":"gotcha","affected_versions":"Pyramid >= 1.4"}],"env_vars":null,"search_vec":"'1.1.0':49 'activ':52 'applic':27 'bind':3,12 'compat':62 'compil':36 'content':31 'current':46 'dynam':30 'enabl':25 'ensur':61 'framework':23,74 'integr':14 'librari':44 'maintain':53 'mako':1,7,16,33,71 'modul':39 'newer':64 'optim':41 'perform':42 'project':57 'provid':8 'pylon':56,75 'pyramid':5,6,21,26,68,70 'python':38,65 'receiv':58 'releas':69 'render':29 'set':10 'system':18 'templat':2,17,34,72 'updat':59 'use':32 'version':48,66 'web':22,73","created_at":"2026-04-11T09:26:51.494422+00:00","updated_at":"2026-04-16T19:44:37.463181+00:00","problems":[{"fix":"Add `config.include('pyramid_mako')` to your application's `__init__.py` file (or wherever your Pyramid application configuration is performed).","cause":"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'.","error":"pyramid.exceptions.ConfigurationError: Renderer factory for .mako is not registered. Perhaps you forgot to include('pyramid_mako')?"},{"fix":"Ensure 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.","cause":"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.","error":"mako.exceptions.TemplateLookupException: Cannot find template 'my_template.mako' (or similar)"},{"fix":"Ensure 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'}`.","cause":"A variable referenced in the Mako template (`${my_variable}`) was not passed to the template context when rendering the template.","error":"NameError: name 'my_variable' is not defined (within a Mako traceback for a template file)"},{"fix":"Import `render_to_response` from `pyramid.renderers` instead: `from pyramid.renderers import render_to_response`.","cause":"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.","error":"ImportError: cannot import name 'render_to_response' from 'pyramid_mako'"},{"fix":"Ensure 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`).","cause":"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.","error":"mako.exceptions.SyntaxException: Undefined filter 'html' (or any other filter)"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.1.0","cli_name":"","cli_version":null,"type":"library","homepage":"https://docs.pylonsproject.org/projects/pyramid-mako/en/latest/","github":"https://github.com/Pylons/pyramid_mako","docs":"https://docs.pylonsproject.org/projects/pyramid_mako/en/latest/","changelog":"https://github.com/Pylons/pyramid_mako/blob/master/CHANGES.txt","pypi":"https://pypi.org/project/pyramid-mako/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}