Install
Keel runs on Pimcore 11 and 12 (classic admin) and Pimcore Studio (2026+). The same bundle serves both. Only the routes file differs.
1. Require the bundle
composer require keel/pimcore-keel
2. Register it
In config/bundles.php:
return [
// …
Keel\Bundle\KeelBundle::class => ['all' => true],
];
3. Add the routes
Create config/routes/keel.yaml. Use one of the two lines:
keel:
resource: '@KeelBundle/config/routes.yaml' # Pimcore 11 or 12, classic admin
# resource: '@KeelBundle/config/routes_studio.yaml' # Pimcore Studio (2026+)
4. Add the licence key
Put the key in .env.local, or set it as a real environment variable on the server. Never commit it.
KEEL_LICENSE_KEY=…
You receive the key with your Keel licence, from whoever supplied Keel to you. It is signed for your company. See Licence.
5. Install the assets and the tables
bin/console assets:install public
bin/console cache:clear
bin/console pimcore:bundle:install KeelBundle # creates Keel's tables
Keel keeps bulk jobs, completeness scores, follows, import previews and Setup → History in eight tables of its own:
keel_bulk_job, keel_bulk_item, keel_completeness_rule, keel_completeness, keel_follow, keel_import_stage,
keel_history and keel_history_item. bin/console keel:install-tables does the same as the install command and can be
repeated on every deploy: it creates only what is missing (also columns a new version adds) and changes nothing when
everything is there. The database user needs the CREATE right for this step only; nothing in a request or a save
creates a table. Pimcore's bundle list shows Keel as installed when all eight tables are there with this version's columns.
Big lists (5,000 items and more) sort through database indexes that you add as a step of their own:
bin/console keel:sort-indexes --dry-run # shows what it would change
bin/console keel:sort-indexes # adds them: one ALTER TABLE per class table
Without them everything works; sorting a big list is slower. See Console commands.
Pimcore Studio
Studio loads Keel as a plugin build. After every Keel update, run assets:install again. Studio hides the Keel tab when the installed build does not match the bundle.
6. Check it works
bin/console keel:setup --check
This only checks. It asks nothing and writes nothing. Each line is one check:
- ✔ fine
- ! worth a look, but Keel works
- ✖ must be fixed: Keel is not installed completely
Under a ! or ✖ line comes the fix, ready to copy. The command ends with exit code 0 when nothing is marked ✖, and 1 otherwise (handy in a deploy script).
What you should see
On a working Studio project:
0 · Install check
-----------------
✔ Keel bundle dev-main is installed
✔ Routes are imported under /pimcore-studio/api/keel
✔ Licensed to Example Ltd
✔ PHP extension sodium is loaded
✔ Scripts and the Studio build are installed and current
✔ Pimcore's settings store is reachable (Customize is saved there)
✔ Keel's database tables are there
✔ Sort indexes of big lists are up to date
✔ List search uses Pimcore's search index (Generic Data Index)
✔ PHP (CLI) allows uploads up to 100 MB, uploads.max_mb is 100
✔ keel.yaml: the classes, fields and switcher paths it names exist
! PHP CLI memory_limit is 256 MB: cache:clear (debug on) may need more
After a keel.yaml change, clear the cache with:
php -d memory_limit=512M bin/console cache:clear
✔ Pimcore's maintenance ran 3 min ago (it runs scheduled publishing)
[OK] Keel is installed. Lines marked ! are worth a look, but nothing is
missing.
Line by line
- Keel bundle … is installed: The bundle is registered (step 2) and its version.
If not ✔: Without step 2 the command does not exist at all - Routes are imported under …: Step 3, and the right file:
/admin/keelfor the classic admin,/pimcore-studio/api/keelfor Studio.
If not ✔: ✖ Create or changeconfig/routes/keel.yamlas shown in the fix - Licensed to …:
KEEL_LICENSE_KEYis set and valid; shows the customer.
If not ✔: ✖ No key, a key that is cut off or has quotes or spaces, or a key past its grace period. ! The key ends within 30 days or is in its grace period: see When a key expires - PHP extension sodium is loaded: Signed licence keys need it.
If not ✔: ✖ Enable sodium for the CLI and the web server - Scripts … are installed and current: Step 5. On Studio also: the installed build is the bundle's build.
If not ✔: ✖bin/console assets:install publicandcache:clear - Pimcore's settings store is reachable: The database table where Customize saves.
If not ✔: ✖bin/console doctrine:migrations:migrate(Keel has no migrations of its own) - Keel's database tables are there: Step 5's
pimcore:bundle:install KeelBundleorkeel:install-tables.
If not ✔: ✖ Runbin/console keel:install-tables - Sort indexes of big lists are up to date: whether
keel:sort-indexeshas something to do.
If not ✔: ! Runbin/console keel:sort-indexes(orcache:clearwhensort_indexes.on_cache_warmupis on) - List search uses …: Whether the Generic Data Index is there.
If not ✔: ! Fine for small lists. Install the index, or setsearch.index: offto hide the line - PHP (CLI) allows uploads up to …: PHP's
upload_max_filesizeandpost_max_sizeagainstuploads.max_mb.
If not ✔: ! Raise both PHP values, or loweruploads.max_mb. The web server's PHP can differ from the CLI. - keel.yaml: the classes, fields and switcher paths it names exist: Class names in
urls,assignmentsandcollections; status fields;{scope}inscope.paths.
If not ✔: ! One line per problem, naming the key, e.g.keel.urls.Product: there is no class Product - PHP CLI memory_limit …: With debug on,
cache:clearcan need more than 256 MB.
If not ✔: ! Usephp -d memory_limit=512M bin/console cache:clear - Pimcore's maintenance ran … ago: When
pimcore:maintenancelast started. Scheduled publishing happens only when it runs.
If not ✔: ! It has not run for over two hours (or not in the last day): set it up as described in Pimcore's maintenance
Pimcore's maintenance
Pimcore's maintenance job must run regularly. It publishes and unpublishes items at the times planned with Schedule… in Keel's editor and in Pimcore's Schedule tab (Scheduled publishing), and it does Pimcore's own clean-up. Without it, planned changes never happen; the Schedule panel then warns editors.
Run it every 5 minutes, and keep a queue worker running for the jobs it sends:
# crontab of the web server user
*/5 * * * * cd /var/www/html && php bin/console pimcore:maintenance
# a long-running worker (supervisord, systemd, …), as in Pimcore's own setup
php bin/console messenger:consume pimcore_core pimcore_maintenance pimcore_scheduled_tasks pimcore_generic_execution_engine
Keep pimcore_generic_execution_engine last: Keel's bulk jobs run there (bulk.transport), and a long job must not hold up the other queues.
With Pimcore's Docker images, a supervisord program can repeat it instead of cron:
[program:maintenance]
command=bash -c 'sleep 300 && exec php /var/www/html/bin/console pimcore:maintenance'
autostart=true
autorestart=true
bin/console keel:setup --check shows when maintenance last ran.
7. Open it
Reload the admin. Keel opens as the first tab. It can be closed, and reopened from its entry in the left menu.
You should see the Overview with one list per data object class in the menu. If you see License required or License expired instead, or no Keel tab, see Troubleshooting.