# Jinja Config Templates !!! info "This feature was introduced in NetBox v4.7." NetBox uses [Jinja](https://jinja.palletsprojects.com/) to render [configuration templates](../../features/configuration-rendering.md). Plugins can extend this rendering pipeline in two complementary ways: 1. **Register custom filters** — make new template filters available by name in every config template. 2. **Inject context variables** — add extra variables that are available inside every config template render. --- ## Registering Jinja Filters ### Via `jinja_env.py` (auto-discovery) Create a file named `jinja_env.py` in your plugin root and expose a dict called `filters`. NetBox will auto-discover and register it when the plugin loads. ```python title="my_plugin/jinja_env.py" def prefix_list(device): """Return all prefixes assigned to a device's interfaces.""" return [ str(ip.address) for iface in device.interfaces.all() for ip in iface.ip_addresses.all() ] filters = { 'prefix_list': prefix_list, } ``` The filter is then available in any config template: ```jinja2 {% for prefix in device | prefix_list %} network {{ prefix }} {% endfor %} ``` ### Via `register_jinja_filters()` You can also register filters programmatically inside your plugin's `ready()` method: ```python title="my_plugin/__init__.py" from netbox.plugins import PluginConfig class MyPluginConfig(PluginConfig): name = 'my_plugin' # ... def ready(self): super().ready() from netbox.plugins.registration import register_jinja_filters from .jinja_env import filters register_jinja_filters(filters) ``` `register_jinja_filters()` accepts a `dict` mapping filter names to callables. It raises `TypeError` if passed a non-dict or if any value is not callable. ### Precedence The full filter precedence from lowest to highest is: **NetBox built-in filters** (e.g. `env`) → **plugin-registered filters** → **instance [`JINJA_FILTERS`](../../configuration/system.md#jinja_filters)**. Instance-level filters always win, so site admins can override anything without touching a plugin. If two plugins register a filter with the same name, the later-loaded plugin's version wins and NetBox will log a warning. For example, if `my_plugin` registers a `prefix_list` filter but a site needs different behaviour, the operator can replace it in `configuration.py` without touching the plugin: ```python title="configuration.py" def prefix_list(device): # Site-local override: include only loopback prefixes return [ str(ip.address) for iface in device.interfaces.filter(type='loopback') for ip in iface.ip_addresses.all() ] JINJA_FILTERS = { 'prefix_list': prefix_list, } ``` --- ## Injecting Context Variables Override `get_jinja_context()` in your `PluginConfig` subclass to inject additional variables into every config template render context. ```python title="my_plugin/__init__.py" from netbox.plugins import PluginConfig class MyPluginConfig(PluginConfig): name = 'my_plugin' # ... def get_jinja_context(self): from .utils import MyNamespace return { 'my_plugin': MyNamespace(), } ``` The returned dict is merged into the template context, so `my_plugin` becomes available by name inside every config template: ```jinja2 {% set records = my_plugin.lookup(device.name) %} ``` !!! warning "Startup cost" `get_jinja_context()` is called on **every** config template render, not once at startup. Keep it fast. Defer expensive lookups to the object you return rather than performing them in `get_jinja_context()` itself. !!! note "Conflict avoidance" Choose context variable names that are unlikely to collide with NetBox's built-in template variables (`device`, `queryset`, etc.) or with those contributed by other plugins. Prefixing with your plugin name is strongly recommended. In addition, avoid top-level app-label names (`dcim`, `ipam`, `virtualization`, etc.). The auto-populated template context maps each app label to a dict of its public model classes; returning a key like `'dcim'` from `get_jinja_context()` will silently replace that entire namespace. !!! note "No per-render context" `get_jinja_context()` receives no arguments — it has no access to the object being rendered or the caller-supplied context. It is intended for plugin-global namespaces (e.g. a lazily-evaluated query helper). Per-object logic belongs in the template itself or in a custom filter. --- ## Rendering Configurations !!! info "This feature was introduced in NetBox v4.8." Devices and virtual machines provide two methods for rendering their configuration outside of a web request, for example from a background job, a custom script, or a management command. For the same template and extra context, these produce the same output as the "Render Config" tab in the UI and the `render-config` REST API endpoint. ### `render_config(config_template=None, extra_context=None)` Renders and returns the object's configuration as text. If `config_template` is not given, the template is resolved from the object, its role, or its platform (in that order). Returns `None` if no template applies. Rendering errors are raised to the caller. ```python from dcim.models import Device device = Device.objects.get(name='router1') config = device.render_config(extra_context={'deploy_id': 42}) ``` !!! tip "Rendering many objects" Resolving each object's config template, and computing any config context that isn't cached, can take extra queries per object. When rendering many objects, preload the template relationships and annotate the queryset so that both are fetched in the same query: ```python devices = ( Device.objects .select_related('config_template', 'role__config_template', 'platform__config_template') .annotate_config_context_data(only_invalidated=True) ) for device in devices: config = device.render_config() ``` ### `get_render_context(extra_context=None)` Returns the context used to render the object's config template: its [config context](../../features/context-data.md) data, then any extra context, then the object itself under its model name (`device` or `virtualmachine`). The object always takes precedence, so extra context can't replace it. !!! note "Permissions" Neither method checks permissions. If you render a configuration on behalf of a user, confirm that the user has the `render_config` and `view` permissions for the object, as the UI and REST API do. If you pass a `config_template` the user selected, also confirm that they have `view` permission for that template.