Skip to content
Get packs

Guide · Open source

How to use Grav: install, add pages and manage plugins

Updated · written with AI from the project's own documentation and checked against our catalogue data

Grav is a file-based content management system for building websites. Pages are written as Markdown text files, templates use Twig, and configuration uses YAML, so no database is needed. This guide shows you how to check the requirements, install Grav, install plugins and themes, and keep everything updated.

Gravgetgrav/grav · ★ 15.7k · MIT

Quick start

  1. 1Check requirements. Confirm PHP 8.3 or higher and an Apache or IIS web server are available.
  2. 2Get Grav. Download a package, run composer create-project getgrav/grav, or clone the GitHub repository into your webroot.
  3. 3Install dependencies. Run bin/grav install from the Grav folder to install plugin and theme dependencies.
  4. 4Browse packages. Run bin/gpm index to see the available plugins and themes.
  5. 5Install a plugin or theme. Run bin/gpm install with the package name you chose.
  6. 6Keep Grav updated. Run bin/gpm selfupgrade for Grav and bin/gpm update for plugins and themes.

Check the requirements before you install Grav

Grav needs PHP 8.3 or higher. The README points to a list of required PHP modules and to separate requirement pages for Apache and IIS web servers, so check those before you begin.

Some install options also need extra tools: Composer for the Composer option, and Git for the GitHub option.

  • PHP 8.3 or higher
  • Apache or IIS web server
  • Composer (only for the Composer install)
  • Git (only for the GitHub install)

Install Grav with Composer, Git or a ready-built package

The README lists three ways to get Grav. You can download a ready-built package from the Downloads page on getgrav.org. Alternatively, Composer creates a new project with the latest stable release in the folder you name.

If you use Git, clone the repository into a folder in your server's webroot, then run the Grav CLI to install plugin and theme dependencies.

composer create-project getgrav/grav ~/webroot/grav cd ~/webroot git clone https://github.com/getgrav/grav.git cd ~/webroot/grav bin/grav install

Add plugins and themes with the Grav Package Manager

You can download plugins or themes manually from the Downloads page, but the README recommends the Grav Package Manager, called GPM. Run the index command to list the available plugins and themes, then install the ones you want by name.

  • List available packages with bin/gpm index.
  • Install one or more plugins or themes by replacing <plugin/theme> with the package name.
bin/gpm index bin/gpm install <plugin/theme>

Update Grav, plugins and themes

Use GPM to update Grav itself and its plugins and themes. The selfupgrade command handles point upgrades within a major version.

Before any upgrade across a major version, read the migration guide. The README says that bin/gpm selfupgrade alone will not take you from Grav 1.x to 2.x, which needs a dedicated migration.

  • Update Grav itself with bin/gpm selfupgrade.
  • Update installed plugins and themes with bin/gpm update.
  • For 1.x to 2.0, follow the migration guide at getgrav.org/migrate-to-2 first.
bin/gpm selfupgrade bin/gpm update

Learn the basics of the Grav platform

Grav uses Markdown for content, Twig for the user interface and YAML for configuration. The official documentation at learn.getgrav.org covers installation, configuration and the Grav CLI in more depth. A Basic Tutorial and a Cookbook of examples are also available there.

Skeletons are free starter sites you can look at to see how a finished Grav site is set up.

  • Read the Configuration guide to understand YAML settings.
  • Try the Basic Tutorial on learn.getgrav.org.
  • Browse the Cookbook for examples.
  • Ask questions in the Grav Discord chat server.

Run the test suite if you contribute to Grav

If you work on Grav's code, first install the dev dependencies with composer install from the Grav root. Then composer test runs the unit tests, and composer test-windows is the Windows version. Static analysis is available through composer phpstan, phpstan-framework and phpstan-plugins.

composer install composer test

What people use it for

  • Building a small or medium content site where pages are plain Markdown files.
  • Running a PHP website without setting up a database.
  • Extending a site with plugins and themes installed through GPM.
  • Starting from a free skeleton and customizing its Twig templates.

Frequently asked questions

Is Grav free to use?

Grav is released under the MIT licence, as stated in the project's listing. The licence text is in the LICENSE file in the repository.

What do I need to run Grav?

You need PHP 8.3 or higher and an Apache or IIS web server. Composer is needed only for the Composer install, and Git only for the GitHub install.

Does Grav need a database?

Grav is a flat-file CMS, so pages are stored as plain files rather than in a database. The README does not describe a database-driven workflow.

How do I install Grav?

You can download a ready-built package from getgrav.org/downloads, run composer create-project getgrav/grav, or clone the GitHub repository and run bin/grav install.

How do I update Grav?

Run bin/gpm selfupgrade to upgrade Grav within a major version. For a move from Grav 1.x to 2.0, follow the migration guide first, since selfupgrade alone does not cover that change.

Is Grav a good alternative to Kirby, Pico, Statamic or Hugo?

Grav is a PHP flat-file CMS that uses Twig and YAML and includes a package manager for plugins and themes. The source does not compare it directly with those projects, so check each one's documentation against your needs.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Grav suits developers and small-to-medium content teams who are comfortable with PHP, Twig, YAML and the command line and want to edit plain text files. It is not a good fit for non-technical users who need a point-and-click builder, or for sites that depend on heavy user accounts or complex database relations.

Install options & downloads