---
name: kirby-upgrade-and-maintenance
description: Upgrades Kirby and maintains dependencies safely using composer audit, plugin compatibility checks, and official docs. Use when updating Kirby versions or making maintenance changes that affect runtime.
---

# Kirby Upgrade and Maintenance

## Quick start

- Follow the workflow below for safe, incremental upgrades.

## KB entry points

- `kirby://kb/panel/compat-k5-k6-migration`
- `kirby://kb/panel/tooling-kirbyup`
- `kirby://kb/glossary/kirbyup`
- `kirby://kb/glossary/plugin`

## Required inputs

- Current and target Kirby versions.
- Environment constraints and downtime tolerance.
- Plugin compatibility risks and rollback expectations.

## Default upgrade checklist

- Read the target version guide and note breaking changes.
- Update `composer.json` constraints, then review the lockfile diff.
- Run project scripts and render representative pages.
- Verify runtime commands and CLI version match.

## Rollback note

- Keep a copy of the previous `composer.lock` and `vendor/` state.

## Rollback checklist

- Restore the previous `composer.lock`.
- Reinstall dependencies and re-run smoke tests.
- Re-render representative pages to confirm behavior.

## Staged upgrade pattern

- Upgrade a single environment/site first, then roll out to others.
- Validate plugins and custom code before multi-site rollout.

## Common pitfalls

- Skipping plugin compatibility checks.
- Upgrading multiple major versions in one jump.

## Workflow

1. Call `kirby:kirby_init` or gather baseline data with `kirby:kirby_info` and `kirby:kirby_composer_audit`.
2. Inventory plugins for compatibility risks: `kirby:kirby_plugins_index`.
3. Use `kirby:kirby_online` to find official upgrade guides and breaking changes for the target version (prefer `kirby:kirby_search` first).
4. Build a project-specific checklist of required code/config changes.
5. Ask for confirmation before dependency updates that change the lockfile.
6. Verify:
   - run project scripts discovered in the composer audit
   - call `kirby:kirby_cli_version` to confirm the installed version
   - ensure runtime commands are in sync: `kirby:kirby_runtime_status` and `kirby:kirby_runtime_install` if needed
   - render representative pages with `kirby:kirby_render_page(noCache=true)`
7. Summarize changes, remaining risks, and a short manual QA checklist.