Kirby meets Composer
Install and update Kirby via 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
You will also need to modify your site's
index.php so that it can find the Kirby installation:
If you moved the
kirby directory to a different directory level (outside of the webroot or into a subdirectory), you will also need to override the
index root like so:
If you prefer to have the CMS installed to the
vendor directory, you can disable the custom path entirely:
index.php file needs to be changed so that it can find Kirby and so that Kirby can find the site data:
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.
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 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.