Skip to content
● Grav 2.0 is officially stable. Read the announcement →

Migrate to Grav 2.0

How to move from Grav 1.7 or 1.8 to Grav 2.0: a fresh install and import workflow that keeps your existing site untouched.

Migrate to Grav 2.0

Grav 2.0 brings significant changes: a new admin, updated libraries, a first-party REST API, and a cleaner plugin model. Because of that, upgrading to 2.0 is not handled in place. The recommended path is to install Grav 2.0 separately, then import your content and configuration from your existing site.

This page covers the why. The how is in the Grav documentation and the migration walkthrough on the blog.

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 its existing plugin and theme ecosystem.

  • Smooth, instant navigation with no full-page reloads
  • Modern UI with thoughtful UX improvements throughout
  • Asynchronous operations such as indexing in the background
  • Built-in CodeMirror editor, Uppy-powered media handling, and a polished component library
  • Collaborative editing via the new Sync plugin
  • 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, with no years of accumulated CVEs to carry along
  • 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 2.0'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.

Migration path

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

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

Grav 1.7.52 is the final stable release in the 1.7 series. It remains a supported option and will continue to receive critical security fixes. There is no fixed deadline to migrate.

How to migrate

There are two supported paths, both starting from a fresh Grav 2.0 install staged alongside your existing site. Your live 1.x site is not modified until you choose to promote the staged install in its place.

Assisted migration (recommended)

The Migrate to Grav 2.0 plugin installs on your existing 1.x site, downloads a fresh Grav 2.0 build, and hands off to a standalone browser wizard that runs the rest of the migration in a clean PHP process. The migrate plugin utilizes a staging workflow that creates a Grav 2.0 site inside your existing 1.7 site. It handles plugin and theme compatibility checks, GPM installs, content copy, user accounts, and the final swap.

This is the right choice for almost every site.

→ Full walkthrough on the blog
→ Reference docs: Assisted Migration

Manual migration

For multi-site installs, complex symlink layouts, externally-mounted user/ folders, or any setup the wizard's assumptions don't fit, a manual migration follows the same steps performed by hand. The Grav docs walk through each phase: stage, plugins, accounts, content, verify, promote.

→ Reference docs: Manual Migration

For plugin and theme developers

If you maintain a plugin or theme, your users can only migrate cleanly if your package is 2.0-ready. The Grav docs cover everything you need:

FAQ

Do I have to migrate?

No. Grav 1.7 will continue to work and will 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 migration plugin's staging workflow produces a full report showing which plugins are 2.0-ready, which need review, and which haven't been ported yet.

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

Yes. The migrate plugin will create a Grav 2.0 instance inside your existing Grav 1.7 site. This allows you to test and compare the 1.7 to 2.0 site to ensure things are working as you expect, then you can 'promote' your Grav 2.0 site which will backup and replace your 1.7 site with 2.0.

What if I have a large site or custom plugins?

That is exactly what the staging workflow is for. It lets you review the migration in advance, identify any issues, and plan the move before making changes. For complex setups the manual migration path gives you finer control.

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. The migration plugin provides a more controlled path that keeps your live site untouched until you're satisfied with the staged 2.0 install.

Resources

Back