Migrate to Grav 2.0

Grav 2.0 brings some significant changes, including a new admin, updated libraries, and a cleaner plugin model. Because of that, upgrading to 2.0 is not handled in place.

Instead, the recommended path is to install Grav 2.0 separately, then import your content and configuration from your existing site.

This page explains the approach and outlines the migration process.

Why upgrade to Grav 2.0?

Grav 1.7 has had a remarkable run, but the platform has reached a natural inflection point. Grav 2.0 is the most significant evolution of the platform since its original launch, and it brings real, tangible benefits across the board.

Admin 2.0 — a truly modern SPA admin

The classic Grav admin has been completely replaced by Admin 2.0, a modern single-page application built on SvelteKit 5, Vite, and Tailwind CSS 4 utilizing the new Grav API plugin. It's fast, responsive, and built from the ground up to work seamlessly with Grav and it's existing plugin and theme ecosystem.

Smooth, instant navigation — no full-page reloads
Modern UI with thoughtful UX improvements throughout
Asynchronous operations such as indexing in teh background
Built-in CodeMirror editor, Uppy-powered media handling, and a polished component library
All the form fields and blueprints you already use carry over — Admin 2.0 is a better experience for the same workflows
TypeScript throughout, with a clean component architecture for future extensibility

A first-party API

Grav 2.0 includes a stable, first-party API as a core component. The API is what powers Admin 2.0, and it opens Grav up to use cases that weren't practical before:

Headless and decoupled frontends — use Grav as a content backend for any framework
CI/CD and automation workflows
Mobile and external integrations
A foundation that plugins can extend with their own custom endpoints

The API opens up many doors for Grav 2.0, and it will allow Grav to be integrated with other systems to a whole new level. It's really the essence that enables Grav 2.0 to become a fully capable headless CMS (if you prefer that approach).

MCP server for AI agents

Grav 2.0 supports a first-party MCP (Model Context Protocol) server, giving agentic AI the same level of access as a human admin — through the same API. Admin 2.0 is for humans. The MCP server is for AI. Both go through one consistent interface.

This isn't AI bolted on as an afterthought — it's a natural extension of Grav 2.0's API-first architecture, ready for the way modern workflows are evolving.

Modern PHP, modern dependencies

Grav 1.7 hit a ceiling at PHP 8.3 because of its library stack. Grav 2.0 lifts that ceiling significantly:

PHP 8.3 minimum, with full support for PHP 8.4 and 8.5
All vendor packages updated to their latest stable versions — Symfony, Twig, and the rest of the stack
Forward-compatible foundation for years of future PHP releases
Cleaner, more modern PHP code throughout the core

Better security

Modern dependencies mean modern security:

All vendor packages on their latest secure releases — no carrying along years of accumulated CVEs
Latest Symfony and Twig versions with all upstream security improvements
Modern PHP versions with current security patches and runtime hardening
API authentication and permission model designed for today's deployment patterns

Better performance

The combination of modern PHP, modern libraries, and a streamlined core delivers measurable performance improvements:

PHP 8.4 and 8.5 bring real runtime performance gains over 8.3
Updated Twig and Symfony versions are faster and more memory-efficient
Admin Next's SPA architecture means fewer round trips and a far more responsive admin experience
API-driven operations are lighter and more cacheable than the old server-rendered admin

Quark 2 — the new default theme

Grav 2.0 ships with Quark 2, a ground-up modernization of the original Quark theme that shipped with Grav 1.5 through 1.8. It's built on Pico CSS v2, Font Awesome 7, and a Cal.com-inspired design system, and it's the recommended foundation for building your own themes on 2.0.

Monochrome palette, refined shadow hierarchy, and generous whitespace
Cal Sans display + Inter body fonts, self-hosted as woff2
Three-state appearance toggle — auto / light / dark — with localStorage persistence and no flash of unstyled content
Configurable accent color driven from the admin color picker
Sticky, animated header with a full-page mobile navigation overlay
Multi-level dropdown navigation with hover-bridge and touch support
Full light and dark palettes for every component
First-class support for the github-markdown-alerts plugin (the successor to markdown-notices)
Multiple page templates out of the box — default, error, blog, item, comments, and modular variants (hero, features, text)

A cleaner foundation for what's next

Grav 2.0 isn't just a one-time refresh — it's the foundation for the next decade of the platform. The API-first architecture, modern stack, and explicit compatibility model mean future improvements can land more cleanly, with less risk to existing sites.

Why use a fresh install?

For a major version change, a fresh install is the safer option. It avoids upgrading a live site while core files, dependencies, and plugins are all changing at the same time.

It also gives you a more predictable migration path:

Your existing 1.7 or 1.8 site stays unchanged until you are ready
Your new 2.0 install starts from a clean baseline
The migration process can identify issues before anything is imported
You can test both sites side by side before switching over

Migration path

Grav 1.7.x  →  Grav 1.7.51
                    ↓
         Grav 2.0 (fresh install + import)

Grav 1.8 beta  →  Grav 2.0 (fresh install + import)

Grav 1.7.51 is the final stable release in the 1.7 series. It remains a supported option and will continue to receive critical security fixes.

How to migrate

1. Back up your site

Before you begin, create a full backup of your site. At minimum, make a copy of your user/ folder or use Grav’s built-in backup tools.

2. Install Grav 2.0 alongside your existing site

Set up a new Grav 2.0 instance separately from your current site.

You can also use the Migrate to 2.0 plugin, which can stage a fresh 2.0 install and add a standalone migration wizard to your web root.

3. Install the migration plugin in the new 2.0 site

The migration plugin is intended as a one-time tool. You can run it from the command line or through the first-run wizard in Admin 2.0.

4. Run a dry run first

Start with a dry run before importing anything. This generates a report showing what would be imported, including content, configuration, plugins, themes, and users.

Review the results, resolve any flagged issues, then run the full migration when you are ready.

5. Verify the new site and switch over

Once the import is complete, review the new site carefully. When everything looks right, switch the 2.0 install into place.

6. Remove the migration plugin

After the migration is finished, the plugin can be uninstalled. It is only needed during the migration process.

What gets imported

Content

Page content imports directly, including Markdown files, frontmatter, and media. Content from Grav 1.7 is fully compatible with Grav 2.0, so no conversion is required.

Configuration

System and site configuration can be imported into the new install. If any deprecated settings are found, they are flagged with suggested replacements.

Core plugins

All official Grav Team plugins will have Grav 2.0-compatible versions. The migration tool installs the correct versions automatically.

Third-party plugins

Many third-party plugins should continue to work, but compatibility depends on how each plugin is maintained. Grav 2.0 adds a compatibility flag to plugin and theme blueprints, and the migration tool uses that information during import:

Plugins marked as compatible with 2.0 are installed automatically
Plugins that only declare 1.7 support are flagged for review
Plugins with no compatibility information are flagged for review
Plugins marked as incompatible are not installed

GPM also follows these compatibility rules and will not install a plugin that is not marked for your Grav version, unless you explicitly override that behavior for testing.

Themes

Themes can be carried over, but they should still be tested against the new core. The migration process flags known compatibility concerns where possible.

Users and accounts

User accounts, roles, and permissions are imported directly.

FAQ

Do I have to migrate?

No. Grav 1.7.51 will continue to work and will still receive critical security fixes. You can move to 2.0 when it makes sense for your site.

Will my plugins work?

In many cases, yes. The dry-run report is the best way to see which plugins are ready and which may need updates or review.

Can I run Grav 1.7 and Grav 2.0 side by side?

Yes. That is the recommended approach. Running both versions side by side gives you time to test before switching over.

What if I have a large site or custom plugins?

That is exactly what dry-run mode is for. It lets you review the migration in advance, identify any issues, and plan the move before making changes.

Why doesn’t GPM upgrade directly to Grav 2.0?

Grav 2.0 is a major version change with enough underlying differences that an in-place upgrade is not considered reliable. Instead, the migration tool provides a more controlled path.

Is there a deadline?

No. There is no fixed deadline for migrating.