!!! info "This feature was introduced in NetBox v4.7."
NetBox uses Jinja to render configuration templates. Plugins can extend this rendering pipeline in two complementary ways:
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.
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:
{% for prefix in device | prefix_list %}
network {{ prefix }}
{% endfor %}
register_jinja_filters()You can also register filters programmatically inside your plugin's ready() method:
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.
The full filter precedence from lowest to highest is: NetBox built-in filters (e.g. env) → plugin-registered filters → instance 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:
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,
}
Override get_jinja_context() in your PluginConfig subclass to inject additional variables into every config template render context.
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:
{% 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.
!!! 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.
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 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.