Skip to content
Grav Documentation
1.7 (Legacy) 2.0 (Stable) Current

Powered by Grav + Helios

Overview

Migrating to Grav 2.0

Grav 2.0 is a major version change. The vendor stack (Symfony, Twig, Monolog, and friends) jumps a generation, the minimum PHP version moves to 8.3, and the classic admin is replaced by Admin 2.0 running against the new Grav API plugin. Because of all that, Grav 2.0 is not delivered as an in-place GPM upgrade. You install Grav 2.0 fresh and import your existing site into it.

This chapter is the reference for that process.

Two Migration Paths

There are two supported ways to move a site from Grav 1.7 or 1.8 to Grav 2.0:

Path When to use Documentation
Assisted (via the Migrate to Grav 2.0 plugin) Almost everyone. Standard single-site installs, typical plugin and theme mixes, default folder layout. Assisted Migration to Grav 2.0
Manual Multisite, complex symlink layouts, externally-mounted user/ folders, sites running custom plugins that haven't been ported yet, or anything else the wizard's assumptions don't fit. Manual Migration to Grav 2.0

Both paths work the same way: stage a fresh Grav 2.0 install alongside the existing 1.x site, copy content and configuration across, verify, then promote. The plugin automates each step and adds a guided wizard. The manual path performs the same steps by hand so you stay in control of every decision.

Important

Whichever path you take, your live 1.x site is not modified until you choose to promote the staged 2.0 install in its place. You can iterate, abandon, or re-run as many times as you need.

Migration Path Summary

TEXT
Grav 1.7.x    →  Grav 1.7.51  →  Grav 2.0 (fresh install + import)
Grav 1.8 beta              →    Grav 2.0 (fresh install + import)

1.7.51 is the final stable release in the 1.7 series. It remains supported and continues to receive critical security fixes for the foreseeable future. There is no fixed deadline to migrate.

What the Migration Covers

The plugin and the manual procedure both handle the same set of inputs:

  • Pages: user/pages/*. Content format is unchanged between 1.7 and 2.0, so pages copy across without conversion.
  • Configuration: user/config/*. Deprecated keys are flagged with suggested replacements.
  • Languages: user/languages/*.
  • Environment overrides: user/env/*.
  • Data: user/data/* (form submissions, login data, anything plugins persist here).
  • Accounts: user/accounts/* including roles and permissions.
  • Plugins and themes: handled through the compatibility: blueprint property. 2.0-flagged packages are pulled fresh from GPM; everything else is either skipped or installed disabled, depending on the policy you choose.

A Behavior Change to Watch For: Twig in Content

Your pages copy across byte-for-byte, but one rendering behavior changed in 2.0 and it is the most common "why did this stop working?" question after a migration. If any of your pages put Twig ({{ ... }} or {% ... %}) directly in their Markdown content, that Twig no longer runs by default.

In Grav 1.7, a page with process.twig: true in its front matter ran its content through Twig with no restrictions. Because page content is authored by anyone with edit access, that was a Server-Side Template Injection risk. Grav 2.0 closes it with two layers: Twig in content is off until an administrator enables it, and when enabled it runs inside a security sandbox that permits only an allow-list of safe tags, filters, and functions.

The practical effect on a migrated site: a page that relied on Twig in its body will show the raw {{ ... }} markup as literal text until you re-enable the feature. This affects content only — the .html.twig files in your theme and plugins are trusted code and are never sandboxed, so normal theme and plugin rendering is unaffected.

Note

Twig in Content is the full guide: how to turn it back on, how the sandbox works, and the recommended alternatives (page templates and shortcodes). After migrating, the Tools → Reports → Twig in Content report in Admin lists every page whose content would leak raw Twig, so you can find affected pages without hunting. Plugin and theme authors should also read the Twig Content Sandbox section of the Developer Upgrade Guide.

For Plugin and Theme Developers

If you maintain a plugin or theme, the migration only succeeds for your users if your package is 2.0-ready. Three reference pages cover the work involved:

  • Plugin Compatibility: declaring the compatibility: flag in your blueprints.yaml so GPM and the migration wizard will install your package on 2.0.
  • Plugin API Integration: exposing your plugin's functionality through the Grav API plugin so Admin 2.0 and external clients can use it.
  • Admin Translations: adapting your languages/*.yaml so labels and help text render correctly in Admin 2.0 (including the optional ICU. namespace for plurals and placeholders).

For a deeper technical reference of everything that has changed under the hood (PHP 8.3 requirements, Symfony 7, Twig 3, Monolog 3, the classic admin removal), see the Developer Upgrade Guide.

And for the work of actually porting code from 1.x to 2.0, the AI-Assisted Development page documents the Claude Code Skills that automate most of the boilerplate.

Troubleshooting

Common issues, lock conflicts, partial-promote recovery, and the compatibility flag fallback rules are collected on the Troubleshooting page.

Coming from Another CMS?

If you're not migrating from an existing Grav site but from another platform, the Migrating to Grav section covers imports from Drupal 7 and WordPress.