Kirby 3 comes with a wealth of new features and changes under the hood. In this guide we go through the steps necessary to upgrade your existing Kirby 2 site to Kirby 3 step by step.
This guide was initially written for upgrading from Kirby 2 to version 3.0. Over the years, newer v3 versions have been released with their own breaking changes etc.
If you are planning to upgrade from Kirby 2 to a higher v3 verison, e.g. 3.9, please also make sure to read the individual migration notes in addition:
While we hope upgrading to version 3 will be rather smooth for you, there are always things that can go wrong during such a process. We urge you to make a backup of your Kirby 2 site in any case.
Kirby 3 now requires PHP 8.0+. Please check if your server supports this PHP version before upgrading.
PHP version support has changed since Kirby 3 was originally released. Because old PHP versions don't receive bugfix or even security updates after a few years, Kirby only supports recent PHP versions. You can find the currently compatible PHP versions in the requirements.
- Replace the old
/kirbyfolder with the new
- The old
index.phpis no longer compatible. Replace it with the new one.
- If you are on an Apache server, replace the old
.htaccessfile with the new one. On other servers, change your server configuration accordingly.
Thumbnails and other media files are now located in
/media and no longer in the
/thumbs folder. Removing it should be enough. Thumbnails will be recreated in the
/media folder automatically afterwards.
To fix many of the sorting number issues in Kirby 2, we changed the ordering number separator of the content folder names from
To change the sorting numbers of all your content folders, put the following script into your document root next to the
index.php and run it with
http://yourdomain.com/upgrade.php. Delete this file afterwards.
If calling such an external script doesn't work in your environment, you can instead add a route in your `site/config/config.php file and open the route path in your browser:
While this might return the error page, it will still do the job.
The Kirby 2 accounts and avatars are not compatible with Kirby 3. Please delete your
assets/avatars folders and install accounts from scratch. If that is not an option, because you have too many accounts, make sure to read the user account migration guide.
Kirby 3 requires a license file instead of the K2 config setting. The license file will be generated when you enter your license information in the Panel. You should remove the K2 config setting.
The custom folder setup is no longer done in
site.php but in your
The Panel folder has been integrated into the
/kirby folder to make updates easier. Therefore, the old Panel folder has to be removed.
Page blueprints are no longer located in
/site/blueprints, but in
/site/blueprints/pages. Moving them to the subdirectory should be enough as a first step. The
site.yml blueprint remains in
If you are updating from an early Kirby 2 version and still use
.php files for your blueprints, change the file extension to
.yml and remove the PHP code from the top of the files.
Before you run any page update scripts or update pages via the Panel, make sure to remove the title field from all your blueprints. Otherwise, the title will be removed.
The old subpage and file settings are no longer compatible with Kirby 3. Files are now added via files sections, subpages via pages sections, and files get their own blueprints with meta data:
The fields will work as before but you might want to restructure them to leverage the new layout features sections, columns and tabs that give you much more control over the look of forms in the Panel.
num blueprint option to set the numbering scheme for pages is no longer set in the parent page blueprint, but in the page blueprint to which the numbering is actually applied. Details: General blueprint options
The option to auto-create subpages via a blueprint setting no longer exists. You can use a
page.create:after hook to achieve the same instead. In fact, you can even define a custom blueprint setting that completely recreates this functionality using Kirby's new
In your blueprint:
The option to make a field readonly (
readonly: true) has been replaced with the
disabled: true. Change your blueprints accordingly.
The following field types no longer exist and have to be replaced:
Also remove or update custom field types, see plugins and extensions.
When moving from the old
image fields to the Kirby 3
files fields, keep in mind that the new fields store their data in
The Kirby 2 Dashboard no longer exists in Kirby 3. With the Dashboard, Panel widgets are gone. Widgets can be replaced with custom Panel sections.
In addition to
Config::set(), the standard way of adding options is now to use a
return statement that returns an array of options:
These options can be called with
sslconfig option has been removed. This should be handled in your
.htaccessfile or in your server configuration.
panel.session.lifetimeare now handled via the session options.
date() method has been removed, because it lead to confusions. It must be replace with the
toDate() field method.
This now works with all date fields, no matter what the date field is called.
When rendering Kirbytext in your templates, replace occurrences of the
kirbytext() helper that convert field values from
You can continue to use the
kirbytext() helper with strings that contain Kirbytext.
Custom routes starting with the string
api will not work anymore, because
api is now reserved by Kirby, unless you change the API slug to something else, see API configuration.
The ways to access arguments from the router has changed from
In your route, you can also pass all arguments explicitly to the
->render() method to make them directly accessible in the controller. Read more ›
Email is now sent using PHPMailer. The way to set email presets and to send email has completely changed, check out the docs
Route filters do no longer exist. Instead you can hook into the route event using the
In Kirby 3, authentication and permissions are now integrated in every method of the Kirby API. You can no longer just call
$page->delete() for example without an authenticated user. That means the user must either be logged in or you need another way to authenticate.
To keep it simple to use the internal APIs to do all sorts of things programmatically and especially when you bootstrap Kirby in your own external script, there is now a way to impersonate an existing users or to create a temporary admin, who can do all those awesome things:
Impersonating an existing user
kirby super user
$pagination->items()was removed, use
Tpl::load()doesn't accept a third argument anymore
excerpt()helper method has been removed and the parameters for the
$field->excerpt()method have changed
Languages are now defined in the
/site/languages folder, not in your
/site/config.phpfile anymore. Users can now add or remove new languages through the Panel, if the
languages option is enabled in the config settings.
$kirby->languages() instead of
Language variables are no longer fetched via
l()/l::get() but via the
User roles can no longer be defined in the config settings, but solely by adding user blueprints.
User permissions are now defined in
.yml files, not
.php files like in Kirby 2. Also, the available permissions have changed to make them easier to implement. On the other hand that means that currently some functionality for fine-grained control of user access is not available.
The user object is no longer accessed via the
$site but via the
$kirby object. All references to
$site->user() have to be replaced by
The toolkit has been completely rewritten, new methods have been added, others removed. Some classes have been removed from the toolkit and moved into their own packages, see list below:
|YouTube, Vimeo and Gist helpers
The Toolkit classes are now in the
Kirby 2 sites with a lot of plugins will require the most effort. Plugins have to be moved to our new plugin syntax. Many plugins developers have already converted their plugins to Kirby 3. Some plugins might no longer be necessary, because their functionality is covered by native Kirby 3 features. Other plugins might not have been ported yet.
As a first step you have to remove your plugins so that your site doesn't break. This means removing the plugin folders, but also removing custom fields from blueprints and removing functionality that is added through these plugins.
As a next step, replace old plugins with new ones where available and/or port your own plugins with the help of our guides.
For plugin developers, read how to migrate your plugin to Kirby 3.
KirbyTags are now defined in a plugin file.
popup: yes property in a
link KirbyTag becomes
Media filenames starting with an underscore (e.g.
_dsc9876.jpg) are ignored in Kirby 3. You need to rename such files.
Please only create tickets if you are pretty sure it is a Kirby issue.