# Migrate from Jinja2

URL: /docs/tutorials/migrate-from-jinja2/
Section: tutorials
Tags: migration, jinja2, tutorial

--------------------------------------------------------------------------------

Migrate from Jinja2 Guide for rewriting Jinja2 templates in Kida syntax. :::note[Not a Drop-In Replacement] Kida is not compatible with Jinja2. Templates must be rewritten using Kida syntax. This guide helps you translate common patterns. ::: Prerequisites Python 3.14+ Familiarity with Jinja2 template syntax Step 1: Install Kida pip install kida Step 2: Update Imports Before (Jinja2): from jinja2 import Environment, FileSystemLoader from markupsafe import Markup After (Kida): from kida import Environment, FileSystemLoader from kida import Markup # Built-in, no markupsafe Step 3: Update Environment Creation Before (Jinja2): env = Environment( loader=FileSystemLoader(&#x27;templates&#x27;), autoescape=select_autoescape(), extensions=[&#x27;jinja2.ext.do&#x27;], ) After (Kida): env = Environment( loader=FileSystemLoader(&#x27;templates&#x27;), autoescape=True, cache_size=400, fragment_ttl=300.0, ) Note: Kida does not use Jinja2-style extensions. For side effects, use &#123;% set _ = expr %&#125;. Step 4: Rewrite Block Endings Convert specific endings to unified &#123;% end %&#125;: Jinja2: &#123;% if condition %&#125; content &#123;% endif %&#125; &#123;% for item in items %&#125; {{ item }} &#123;% endfor %&#125; &#123;% block content %&#125; ... &#123;% endblock %&#125; Kida: &#123;% if condition %&#125; content &#123;% end %&#125; &#123;% for item in items %&#125; {{ item }} &#123;% end %&#125; &#123;% block content %&#125; ... &#123;% end %&#125; Step 5: Update Custom Filters Before (Jinja2): def format_money(value, currency=&#x27;$&#x27;): return f&#x27;{currency}{value:,.2f}&#x27; env.filters[&#x27;money&#x27;] = format_money After (Kida): def format_money(value, currency=&#x27;$&#x27;): return f&#x27;{currency}{value:,.2f}&#x27; env.add_filter(&#x27;money&#x27;, format_money) # Or use the decorator @env.filter() def format_money(value, currency=&#x27;$&#x27;): return f&#x27;{currency}{value:,.2f}&#x27; Step 6: Update Custom Tests Before (Jinja2): def is_prime(n): return n &gt; 1 and all(n % i for i in range(2, n)) env.tests[&#x27;prime&#x27;] = is_prime After (Kida): env.add_test(&#x27;prime&#x27;, is_prime) # Or use the decorator @env.test() def is_prime(n): return n &gt; 1 and all(n % i for i in range(2, n)) API Mapping Jinja2 Kida Environment Environment FileSystemLoader FileSystemLoader DictLoader DictLoader Template.render() Template.render() Template.render_async() Template.render_async() Markup (markupsafe) Markup (built-in) env.filters[name] = func env.add_filter(name, func) env.tests[name] = func env.add_test(name, func) env.globals[name] = value env.add_global(name, value) Syntax Translation Jinja2 Kida &#123;% endif %&#125; &#123;% end %&#125; &#123;% endfor %&#125; &#123;% end %&#125; &#123;% endblock %&#125; &#123;% end %&#125; &#123;% endmacro %&#125; &#123;% end %&#125; &#123;&#123; x \| filter &#125;&#125; &#123;&#123; x \|> filter &#125;&#125; (pipeline) &#123;% if %&#125;...&#123;% elif %&#125;...&#123;% endif %&#125; &#123;% match %&#125;...&#123;% case %&#125;...&#123;% end %&#125; N/A &#123;% cache key %&#125;...&#123;% end %&#125; New Features After migrating, explore Kida-only features: Pipeline Operator {{ title |&gt; escape |&gt; upper |&gt; truncate(50) }} Pattern Matching &#123;% match status %&#125; &#123;% case &quot;active&quot; %&#125; ✓ Active &#123;% case &quot;pending&quot; %&#125; ⏳ Pending &#123;% case _ %&#125; Unknown &#123;% end %&#125; Block Caching &#123;% cache &quot;sidebar-&quot; + user.id %&#125; {{ render_sidebar(user) }} &#123;% end %&#125; Verification After migration, verify templates render correctly: from kida import Environment env = Environment() template = env.from_string(&quot;Hello, {{ name }}!&quot;) result = template.render(name=&quot;World&quot;) assert result == &quot;Hello, World!&quot; print(&quot;✅ Migration successful!&quot;) Common Issues Markup Import Error: ImportError: cannot import name 'Markup' from 'markupsafe' Fix: Import from Kida: from kida import Markup # Not from markupsafe Filter Registration Error: TypeError: 'FilterRegistry' object does not support item assignment Fix: Use add_filter(): env.add_filter(&#x27;name&#x27;, func) # Not env.filters[&#x27;name&#x27;] = func Block Endings Error: TemplateSyntaxError: Unexpected tag 'endif' Fix: Use unified &#123;% end %&#125;: &#123;% if x %&#125;...&#123;% end %&#125; # Not &#123;% endif %&#125; See Also Control Flow — Pattern matching syntax Comparison — Kida vs Jinja2 Performance — Benchmark results

--------------------------------------------------------------------------------

Metadata:
- Word Count: 546
- Reading Time: 3 minutes