Kirby meets Composer
This tutorial describes one of several ways you can install and update Kirby. See the overview page for all supported ways.
If you have never used Composer before, you first need to install it. Please follow the instructions on the Composer website.
Once you have installed Composer, run the following command to set up a new Kirby installation with the Starterkit:
composer create-project getkirby/starterkit your-project
You can alternatively set up the Plainkit if you want:
composer create-project getkirby/plainkit your-project
All Composer packages are generally installed in the
vendor directory. Kirby however is automatically installed in the
kirby directory, so that you can get started right away.
It is generally recommended to exclude the
vendor as well as the
kirby directory from version control. If you use Git, add them to your
.gitignore file. Your
.gitignore should now look something like this:
... /kirby /vendor ...
If you have an existing site and want to use Composer with it, that's possible as well.
The Composer magic is all contained in the
composer.json file. The most basic version looks like this:
Save this file in the root of your Kirby project and run the following command:
If you want to use a different location for the
kirby directory, you can change it in your
Afterwards update the installation with:
cd your-project composer update
If you prefer to have the CMS installed to the
vendor directory, you can disable the custom path entirely:
Please note that you will need to modify your site's
index.php to load the
vendor/autoload.php file instead of Kirby's
If you want to update Kirby to the latest version, all you need to do is to run the following command:
composer update getkirby/cms
Composer will now look for the latest version that matches your version constraint in the
composer.json file. You can learn more about this in the Composer documentation.
By changing the Kirby version in your
composer.json, you can make Composer install a different version of Kirby. Very useful is the special version
dev-develop, which will install the current development version of Kirby straight from GitHub.
Installing plugins with Composer
Many Kirby 3 plugins also support installation via Composer. As you now have a Composer setup, you only need to add them to your
composer.json file and run
composer update. This will automatically install the plugins to the
site/plugins directory for you.
Alternatively, you can run
composer require <plugin-name>, which will install the plugin and add it to your
composer.json for you.
If you want, you can add the plugin to your
.gitignore file. If you prefer, you can skip this step and commit the plugin code to your site repo (e.g. if you want to enable other team members to work on the site without having to run Composer or if you don't want to run Composer when deploying your site).
plugins directory path
plugins directory is in a non-standard location, you can change it like this:
Of course, you can also install other dependencies like general PHP libraries this way. The libraries you install will automatically be available from your site's code, e.g. in your templates, controllers and models.