"Major version" usually means "clear your weekend." A Filament v5 upgrade breaks that expectation. Filament v5 shipped on January 16th, 2026 with exactly one reason to exist: support for Livewire 4. There are no new features over v4 and no breaking changes to your forms, tables, actions, or resources. Dan Harrin bumped the major version purely so that apps not depending on Livewire directly wouldn't get their custom Livewire code broken during a routine composer update.
That makes this one of the calmest major upgrades in the Laravel ecosystem - but "calm" isn't "do nothing." The genuine work sits in three places: any custom Livewire components you wrote by hand, your Tailwind v4 build, and third-party plugin compatibility. By the end of this guide you'll have run the official upgrade script, fixed the handful of Livewire 4 edits that actually bite, confirmed your theme compiles on Tailwind v4, audited your plugins, and proven the whole thing green with your test suite. Every command below is verified against the official Filament v5 upgrade guide - your automated script output will still be unique to your app, so read it before you run it.
Check your prerequisites and back up#
Before you touch a single dependency, confirm your app clears Filament v5's four hard requirements and give yourself a clean rollback point. Filament v5 needs PHP 8.2 or higher, Laravel 11.28 or higher, Livewire 4.0 or higher, and Tailwind CSS 4.0 or higher. Most teams already on a current Filament v4 app clear the first two comfortably; the Tailwind requirement is the one that catches people still running a v3 theme.
Start by taking stock of where you actually are. Laravel's about command gives you PHP and framework versions at a glance, and Composer tells you your current Filament release:
php artisan about --only=environment
composer show filament/filament | grep versions
composer show livewire/livewire | grep versions
Then create a rollback point you can trust. A major upgrade should never begin on a dirty working tree, and you want a database snapshot in case a plugin migration misbehaves:
# Commit or stash everything first
git status
git checkout -b upgrade/filament-v5
# Snapshot the database (adjust for your connection)
php artisan db:show
mysqldump -u root -p my_app > storage/backups/pre-filament-v5.sql
If you know Tailwind v3 is your weak point, deal with it as its own task before the Filament upgrade rather than mid-flight - our walkthrough of the Tailwind v3 to v4 upgrade tool covers the automated path. Teams that lean on automated upgrade tooling as a habit will also find Rector for automating Laravel upgrades pairs well with this kind of work. With prerequisites confirmed and a backup on disk, you're ready to let Filament's own tooling do the heavy lifting.
Install the Filament upgrade package#
Install the filament/upgrade package as a dev dependency - it ships the script that inspects your code, flags compatibility issues, and applies the mechanical changes for you. This package is throwaway tooling: you pull it in, run it once, and remove it when you're done, so it never pollutes your production dependency graph.
composer require filament/upgrade:"^5.0" -W --dev
The -W flag (short for --with-all-dependencies) lets Composer update whatever else it needs to resolve the upgrade package cleanly, which matters when your existing constraints are tight. On Windows PowerShell the caret in "^5.0" gets stripped by the shell, so use a tilde constraint instead:
composer require filament/upgrade:"~5.0" -W --dev
Installing the package alone changes nothing about your app's behaviour - it simply puts vendor/bin/filament-v5 on disk, ready to run. That script is the next step, and it's where the automation earns its keep.
Run the automated upgrade script#
Run the upgrade script and let it rewrite the repetitive parts of the migration for you. It scans your codebase for patterns that changed between v4 and v5, applies the safe automatic edits, and - crucially - prints a set of composer commands tailored to your specific project. Because that output is unique to your dependency set, you should read it rather than blindly pasting it.
vendor/bin/filament-v5
The script walks your app/, resources/, and config directories, and reports what it changed and what it couldn't. Filament's official guide is explicit that most of the work is repetitive and best left to the script, with only a small amount of manual follow-up expected afterward. Review its diff before committing:
git diff --stat
git diff
Take the script's plugin warnings seriously. If it flags a third-party package as unavailable for v5, note it now - you'll decide what to do with it when you audit plugins later. For the moment, resist the urge to hand-edit anything the script touched; let it finish the job, then move on to actually pulling in Filament v5 itself.
Bump your Filament and dependency constraints#
Apply the composer commands the script printed, which move your constraint from filament/filament:^4.0 to ^5.0 and pull the new release. The script generates these tailored to your project, but for a typical app they follow this shape - require the new version without updating, then resolve everything in one pass:
# These come from the script output - yours may differ
composer require filament/filament:"^5.0" -W --no-update
composer update
The --no-update flag stages the version change in composer.json without immediately resolving, so the subsequent composer update can settle Filament, Livewire, and every plugin together in a single dependency-resolution pass instead of fighting each other one at a time. On Windows PowerShell, swap ^5.0 for ~5.0 here too.
Once Composer reports a successful update, the upgrade package has done its job and you can remove it:
composer remove filament/upgrade --dev
At this point your composer.json is on Filament v5. If your app is a straightforward Filament panel with no custom Livewire components and no bespoke theme, you may already be done - clear your caches, rebuild assets, and run your tests (the final step). Most production apps have accumulated at least some custom code, though, and that's where the remaining steps come in.
Upgrade your custom Livewire components#
Because v5 exists to adopt Livewire 4, any Livewire components you wrote by hand - outside Filament's own resources and pages - need a pass against the Livewire 4 upgrade guide. Filament's internals are already updated for you; this step is only about your custom components, custom form fields, and custom table columns that render their own Blade and JavaScript. There are four changes that actually bite in practice, and the rest are edge cases.
First, component tags must be self-closing. Livewire 4 added slot support, which means an unclosed <livewire:...> tag now swallows everything after it as slot content and silently fails to render:
{{-- Livewire 3 - rendered fine unclosed --}}
<livewire:user-stats :user="$user">
{{-- Livewire 4 - must be self-closed --}}
<livewire:user-stats :user="$user" />
Second, wire:model no longer reacts to events bubbling up from child elements. In v3, putting wire:model on a wrapper (a modal, an accordion) would capture input events from nested fields; in v4 it only listens to events on the element itself. If you relied on the old behaviour - common in custom modal fields - add the .deep modifier to restore it, as the Livewire wire:model documentation describes:
{{-- Restore v3 behaviour on container elements --}}
<div wire:model.deep="value">
<input type="text" />
</div>
Third, several config keys in config/livewire.php were renamed. The two you're most likely to hit are the layout and placeholder keys:
// Before (Livewire 3)
'layout' => 'components.layouts.app',
'lazy_placeholder' => 'livewire.placeholder',
// After (Livewire 4)
'component_layout' => 'layouts::app',
'component_placeholder' => 'livewire.placeholder',
Fourth, wire:transition now uses the browser's native View Transitions API instead of wrapping Alpine's x-transition. Basic wire:transition still fades elements in and out, but modifiers like .opacity, .scale, .duration.200ms, and .origin.top have been removed - strip them out or replace them with CSS. If your custom fields hook Alpine into Livewire state, the patterns in managing modal state with wire:entangle and Alpine are worth re-reading against v4, and if you maintain a custom Filament form field component that injects its own JavaScript, this is the moment to test it end to end. After editing, reinstall Livewire and clear the compiled views:
composer require livewire/livewire:"^4.0"
php artisan optimize:clear
One more note: full-page custom components should move to Route::livewire('/dashboard', Dashboard::class), which is now the recommended registration and is required for single-file and multi-file component formats. Standard Filament resource pages are unaffected - this is purely for components you route yourself.
Confirm your theme runs on Tailwind v4#
Filament v5 requires Tailwind CSS v4, so confirm your panel's theme compiles against it before you ship. If you're coming from a recent Filament v4 app you're likely already on Tailwind v4 - Filament moved to it during the v4 line - but any project still carrying a Tailwind v3 custom theme needs to upgrade the CSS toolchain as part of this move. The tell-tale sign you're still on v3 is a tailwind.config.js full of theme.extend and @tailwind directives rather than a CSS-first @import "tailwindcss".
For a Filament custom theme, the entry stylesheet should import Tailwind and register Filament's preset the v4 way:
/* resources/css/filament/admin/theme.css */
@import 'tailwindcss';
@import '../../../../vendor/filament/filament/resources/css/theme.css';
@source '../../../../app/Filament';
@source '../../../../resources/views/filament';
Bump the Tailwind packages and rebuild so the new engine picks up your @source globs:
npm install tailwindcss@^4 @tailwindcss/vite@^4
npm run build
Tailwind v4's CSS-first configuration is a genuine shift in how you express design tokens and variants - if your theme leans on custom colors or dark mode, our guide to CSS-first dark mode and custom variants in Tailwind v4 walks through the new syntax, and if you maintain a white-label Filament theme the branding patterns there translate directly. Once your theme builds without warnings, the last external risk is the plugins you don't control.
Audit your third-party plugins for v5 support#
Check every third-party Filament plugin in your composer.json for a v5-compatible release, because an unmigrated plugin is the single most likely thing to block your upgrade. Filament's own code is source-compatible, but a plugin still constrained to filament/filament:^4.0 will halt composer update cold. List what you actually depend on:
composer show "filament/*"
composer show | grep -i filament
For each plugin, check its packagist page or GitHub releases for a v5 tag. You have four realistic options, roughly in order of preference: wait for the author to ship a v5 release if one is imminent; replace the plugin with a v5-compatible alternative; temporarily remove it from composer.json and gate the feature behind a flag until it's ready; or, if you rely on it heavily, open a pull request to help the author upgrade. Filament's guide explicitly endorses all four paths.
If a plugin provided functionality you can now build natively - say a table filter or a simple column - it may be cheaper to inline it than to wait. Our walkthroughs of custom table filters in Filament and the repeater and builder for nested form data both port cleanly to v5 since the forms and tables APIs are unchanged. Resolve every plugin to a v5-ready state - or a documented, gated removal - before you consider the dependency work finished. Then it's time to prove the whole upgrade actually works.
Rebuild assets, clear caches, and run your tests#
Rebuild your frontend, flush every cache, and run your full test suite - this is where you confirm the upgrade is real rather than just resolved. Filament and Livewire both ship compiled assets and cached views that must be regenerated after a major bump, and a stale cache is the most common cause of "it upgraded but the panel looks broken" reports.
php artisan optimize:clear
php artisan filament:optimize-clear
npm run build
php artisan filament:assets
Then let your tests be the judge. A Filament app with a decent feature suite will surface most regressions here - resource pages that fail to mount, actions whose modals don't open, custom fields that stopped binding:
composer test
If anything fails, fix it and run composer test again until the suite is green - don't merge on a red build. Follow the automated suite with a two-minute manual smoke test of the paths tests rarely cover: log into the panel, open a resource list and confirm tables and filters render, create and edit a record, fire a bulk action, and trigger any custom action modal. For the interactive surfaces that unit tests can't fully exercise, browser testing with Pest 4 and Playwright is worth adding to your pipeline so the next upgrade is even less nerve-wracking.
That's the whole upgrade. You confirmed prerequisites, ran filament/upgrade and its generated commands, patched the Livewire 4 changes in your custom components, rebuilt your Tailwind v4 theme, cleared incompatible plugins, and proved it green. The reward for the move is everything Livewire 4 unlocks in your panel - reach for Livewire 4 Islands to lazy-load heavy components to speed up dashboard widgets, wire up live dashboard metrics with wire:poll, and layer in newer Filament v5 conveniences like status tabs with counts on a list page. None of that was possible on v4 - and now the door's open.
FAQ#
Is it safe to upgrade from Filament v4 to v5?
Yes - this is one of the lowest-risk major upgrades Filament has shipped. Because v5 exists solely to support Livewire 4 and adds no new features, there are no breaking changes to your forms, tables, actions, or resources. The main risks are external to Filament itself: any custom Livewire components you wrote, your Tailwind v4 build, and third-party plugins that haven't published a v5 release yet. Work on a branch with a database backup, run the automated script, and let your test suite confirm the result before merging.
Does Filament v5 have breaking changes?
Filament v5 has essentially no breaking changes of its own - the framework's forms, tables, actions, and resources behave exactly as they did in v4. The breaking changes you need to handle come from Livewire 4, which v5 depends on: component tags must be self-closed, wire:model no longer captures events from child elements without the .deep modifier, several config/livewire.php keys were renamed, and wire:transition dropped its Alpine modifiers in favour of the native View Transitions API. Those only affect custom Livewire code, not Filament's built-in components.
Does Filament v5 require Livewire 4?
Yes. Livewire 4 support is the entire reason Filament v5 exists as a major version. The Filament team bumped the major number specifically so that projects not requiring livewire/livewire directly wouldn't have their custom Livewire code broken during an unrelated composer update. If you have hand-written Livewire components, you should also follow the official Livewire 4 upgrade guide as part of the move, since that's where the real manual edits live.
Does Filament v5 require Tailwind v4?
Yes - Tailwind CSS v4.0 or higher is one of Filament v5's four hard requirements, alongside PHP 8.2+, Laravel 11.28+, and Livewire 4.0+. In practice, recent Filament v4 apps are already on Tailwind v4 because Filament adopted it during the v4 line, so many teams have nothing to do here. The exception is any project still running a Tailwind v3 custom theme, which needs the CSS toolchain upgraded - moving from tailwind.config.js and @tailwind directives to the CSS-first @import "tailwindcss" approach - before the panel will compile.
How long does a Filament v5 upgrade take?
For a standard Filament panel with no custom Livewire components and a theme already on Tailwind v4, the upgrade can take fifteen minutes: install the upgrade package, run the script, apply the composer commands, clear caches, and test. Budget closer to two hours for a production app that has custom Livewire components to patch, a Tailwind v3 theme to migrate, and several third-party plugins to verify. The variable isn't Filament - it's how much bespoke code and how many plugins you've accumulated around it.
What happens to my custom columns in Filament v5?
Your custom table columns keep working - Filament v5 makes no breaking changes to the tables API, so a column extending Filament's column classes behaves exactly as it did in v4. The only thing to re-test is a custom column that renders its own Blade view with embedded JavaScript or Alpine, because that markup runs under Livewire 4 now. Check that any inline wire: directives still behave as expected and that self-closing tag rules are respected, but you do not need to rewrite the column's PHP.
Do third-party Filament plugins work with v5?
Some do immediately and some need a new release - it depends entirely on each plugin author. Because Filament's forms, tables, and actions APIs are unchanged, many plugins are source-compatible and only need their version constraint widened to allow filament/filament:^5.0. Others will genuinely block your composer update until the author ships a v5 tag. Audit every filament/* package before upgrading, and for each one either wait for a v5 release, swap in an alternative, temporarily remove it behind a feature flag, or contribute a pull request to help the maintainer upgrade.