Tailwind CSS v3とv4の違い｜破壊的変更と移行手順をv4.3.3の実ビルドで検証

Tailwind CSS v4.0 は2025年1月22日にリリースされ、npmの最新版は2026年9月23日時点で 4.3.3（2026年7月16日公開）です。v3からの移行でつまずくのは、削除されてビルドが落ちるクラスではなく、クラス名が残ったまま出力されるCSSだけが変わる箇所と、エラーを出さずに無効なCSSへ変換される旧記法です。この記事では v3.4.19 と v4.3.3 を同じ環境に入れて同一クラスをビルドし、生成CSSを突き合わせた実測をもとに、差分・移行手順・判断基準を整理します。

まとめ：v3とv4の違いで押さえる5点

先に結論を挙げます。

• 設定の置き場所が変わった。tailwind.config.js は自動で読まれなくなり、テーマはCSSの @theme に書く。JS設定を続けるなら @config で明示的に読み込む。
• ビルドが通るのに見た目だけ変わるクラスがある。shadow-sm rounded-sm blur-sm は名前が一段ずつずれ、ring は3pxから1pxへ、border の既定色は gray-200 から currentColor へ変わった。クラス名は残るのでビルドは成功する。
• 旧記法はエラーにならず無効なCSSになる。bg-[--brand] は v4.3.3 で background-color: --brand; という効かない宣言を出力する。
• 対応ブラウザが切り上がった。公式の対応対象はSafari 16.4・Chrome 111・Firefox 128以降。v4.1では旧ブラウザ向けフォールバックも改善されたが、それ以前のブラウザで全機能が同等に動く保証はない。
• v3は放置されていない。npmの v3-lts タグは 3.4.19（2025年12月10日公開）で、v4.0の公開後にもv3系のリリースが出ている。古いブラウザやSassが外せない案件は据え置きが現実的な選択肢になる。

以下、それぞれを実測値と公式の記述で裏づけていきます。

v3とv4を分ける4つの土台変更

設定方式の変更：JavaScriptからCSSへ

v3では tailwind.config.js にテーマと content を書き、CSS側は @tailwind ディレクティブ3行で読み込む構成でした。v4はこれをCSSに一本化します。

/* v3.4 */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* v4.3 */
@import "tailwindcss";

@theme {
  --color-brand: oklch(0.7 0.15 250);
  --breakpoint-3xl: 120rem;
}

--color-brand を定義すれば bg-brand や text-brand が使えるようになると同時に、Tailwindを通さない素のCSSからも var(--color-brand) で参照できます。ただし @theme に書いた変数が常にCSSへ出るわけではありません。v4.3.3 で確かめたところ、既定ではユーティリティとして使われた変数だけが出力され、どこからも参照されていない変数は省かれます。JavaScriptから読むためだけに定義した変数を消さないためには @theme static を使います。v3にあった resolveConfig は削除されており、JavaScript側でテーマ値が要るときは getComputedStyle(document.documentElement) で読む形に変わりました。

JS設定は互換のため残っていますが、自動検出はされません。既存の tailwind.config.js を使い続けるなら、CSSから明示的に読み込みます。

@import "tailwindcss";
@config "../../tailwind.config.js";

ただし移せない設定があります。公式アップグレードガイドは corePlugins・safelist・separator の3つを「v4.0ではサポートされない」と明記しています。このうち safelist の代替は @source inline() ですが、これが追加されたのは v4.1.0（2025年4月1日公開）です。v4.0系には @source inline() はありませんが、必要なクラス名を列挙したファイルを @source で走査対象に追加する方法は使えました。当時の移行記事を読むときは、対応する版と記法を確認してください。

ビルド性能の比較と測定条件

公式ブログのベンチマークは、自社製品Catalystを対象にした中央値として次の数字を出しています。

「100倍速い」という表現が独り歩きしていますが、182倍が出るのは新しいクラスが1つも増えていない再ビルドという条件付きです。新規CSSが増えない再ビルドと、CIなどのクリーンビルドでは、比較すべき計測条件が異なります。3.78倍はCatalystでのフルビルドの測定値であり、各プロジェクトのCIでも同じ倍率になるとは限りません。

最小構成で計測すると数字の桁が変わります。検証条件は macOS（Intel x86_64）・Node.js v26.5.0、入力はクラス10個を含むHTML 1枚のみ、出力先は /dev/null、ウォームアップとして各版1回実行したあとに [email protected] と @tailwindcss/[email protected] のCLIをそれぞれ5回ずつ実行し、time の real 値を平均したものです。結果は v3 が1.526秒、v4 が0.656秒でした。Node.jsのプロセス起動時間を含む値なので、公式ベンチマークとは測定範囲が異なります。この比較だけではプロジェクト規模と高速化倍率の関係までは判断できず、規模の影響を調べるには同じ測定方法で入力規模を変えた比較が必要です。

付随して、v4はインポート解決とベンダープレフィックス付与を内蔵しました。postcss-import と autoprefixer は設定から外せます。

対応ブラウザの下限と旧版向けフォールバック

公式アップグレードガイドは「Tailwind CSS v4.0 is designed for modern browsers and targets Safari 16.4, Chrome 111, and Firefox 128」と書き、@property と color-mix() をコア機能が使っているため「will not work in older browsers」と続けています。Safari 16.4 は2023年3月27日リリースなので、この下限はiOS 16.4以降の端末に相当します。

ただし「それ以前では一切表示されない」と読むのは行き過ぎです。v4.1 で旧ブラウザ向けのフォールバックが入り、公式ブログは oklab で定義した色が古いSafariでも描画されること、@property に依存する影・変形・グラデーションが古いSafariとFirefoxでも動くことを挙げています。同じ記事が「Tailwind CSS v4 is still designed for modern browsers like Safari 16.4 and up」と念を押したうえで「at least now your sites will render and be usable in older browsers」と書いており、公式の対応対象は変わらないまま、劣化の仕方が穏やかになったというのが正確な理解です。

したがって、iOS 16.3以前を公式サポート対象に含む案件では「If you need to support older browsers, we recommend sticking with v3.4 for now」という公式推奨どおり v3.4 の継続が基本で、それでもv4へ上げるなら対象端末での実機確認が前提になります。ガイドは互換モードを「actively exploring」と書いていますが、2026年9月時点で提供はされていません。

ビルドツール別のパッケージ構成

v3では tailwindcss ひとつがPostCSSプラグインでもCLIでもありました。v4はそれぞれ別パッケージです。

webpack専用プラグインは v4.2.0（2026年2月18日）で追加された新顔です。これらは本体と同じ版番号で並行リリースされており、2026年9月23日時点ではいずれも 4.3.3 です。Viteを使っているなら、PostCSSプラグイン経由ではなく @tailwindcss/vite へ移すことを公式が推奨しています。

ビルドは通るのに見た目だけ変わるクラス

移行で最も厄介なのがこの層です。クラス名がv4でも有効なので、ビルドもリントも通り、ブラウザで見て初めて気づきます。以下はすべて v3.4.19 と v4.3.3 で同じHTMLをビルドし、生成CSSを直接比較した結果です。

shadow・rounded・blurの名称と値の対応

v4は「素の名前（shadow・rounded・blur）」にも値の名前を与える方針でスケールを振り直しました。その結果、v3の値がひとつ小さい名前へスライドしています。v4.3.3 同梱の theme.css から実際の値を抜くと対応がはっきりします。

実際に v4.3.3 で shadow-sm をビルドすると、出力される --tw-shadow は 0 1px 3px 0 …, 0 1px 2px -1px … でした。v3で書いた shadow-sm をそのまま残すと、影が一段濃くなります。drop-shadow-* と backdrop-blur-* も同じ規則でずれます。

ring と outline の既定値

v3の ring は 3px のリングを既定色 blue-500 で描いていました。v4.3.3 の生成CSSでは幅が calc(1px + var(--tw-ring-offset-width))、色が var(--tw-ring-color, currentcolor) です。border や outline と揃えるための変更で、v3と同じ見た目が要るなら ring-3 と色指定の両方を書き足します。

outline-none はもっと分かりにくく壊れます。v3は「透明な2pxのアウトライン」を出していました。強制カラーモードでフォーカス位置を失わせないための実装です。

/* v3.4.19 の出力 */
.outline-none {
  outline: 2px solid transparent;
  outline-offset: 2px;
}

/* v4.3.3 の出力 */
.outline-none {
  --tw-outline-style: none;
  outline-style: none;
}

v4の outline-none は名前どおりアウトラインを消します。v3の挙動に相当するのは outline-hidden です。focus:outline-none を機械的に残すと、アクセシビリティ上の配慮が黙って外れるので、この置換だけは優先度を上げてください。

プロジェクト全体をv3の値に戻したい場合は、公式が互換用のテーマ変数を用意しています。ただしガイド自身が「compatibility reasons のためであり v4.0 の慣用的な書き方ではない」と注記しているので、移行期間の一時措置として使う前提です。

@theme {
  --default-ring-width: 3px;
  --default-ring-color: var(--color-blue-500);
}

border の既定色と space-y-* のセレクタ

v3のPreflightは *, ::before, ::after に border-color: #e5e7eb（gray-200）を当てていました。v4.3.3 の出力を見ると該当箇所は border: 0 solid だけで、色指定がありません。つまり currentColor です。border とだけ書いて色を指定していない箇所は、テキスト色の枠線に変わります。全体をv3の見た目へ戻すなら、ベースレイヤーで色を戻します。

@layer base {
  *, ::after, ::before, ::backdrop, ::file-selector-button {
    border-color: var(--color-gray-200, currentColor);
  }
}

space-y-* はセレクタごと作り替えられました。v3は後続兄弟結合子 ~ を使って上マージンを当てていましたが、v4は最後の子以外に下マージンを当てます。次のコードは差分に関係する宣言の抜粋で、変数の初期化などは省略しています。

/* v3.4.19 */
.space-y-4 > :not([hidden]) ~ :not([hidden]) {
  margin-top: calc(1rem * calc(1 - var(--tw-space-y-reverse)));
}

/* v4.3.3 */
:where(.space-y-4 > :not(:last-child)) {
  margin-block-end: calc(calc(var(--spacing) * 4) * calc(1 - var(--tw-space-y-reverse)));
}

ここで見落としやすいのが :where() です。公式ガイドのコード例には :where() が書かれていませんが、v4.3.3 が実際に吐くCSSは :where() で包まれており、詳細度が0になっています。自前のCSSで上書きしやすくなった一方、これまで詳細度の高さに助けられていた指定は逆転する可能性があります。あわせてマージンの向きが上から下へ、物理プロパティから論理プロパティへ変わるため、インライン要素に space-x-* を当てていた箇所や子要素に個別のマージンを足していた箇所は目視確認が要ります。公式は解決策として、flex か grid に変えて gap を使う移行を勧めています。divide-x-* と divide-y-* も同じ理由で同じ変更が入っています。

色そのものも変わっています。既定パレットの記述が rgb から oklch になり、sRGBより広い色域を使えるようになりました。ただしこれは「派手になる」変更ではなく、公式はv3の色バランスを保つよう再設計したと説明しており、アップグレード時に破壊的変更として体感される想定ではないとしています。色の差分を確認する際は、ブランドカラーを使う画面に加え、通常のsRGB環境とP3対応環境で主要画面の表示を比較してください。

エラーを出さずに無効なCSSになる旧記法

前章は「値が変わる」話でしたが、こちらは「出力されたCSSが効かない」話です。ビルドログには何も出ません。

CSS変数を任意値で渡す記法の変更と移行先

v3では角括弧にCSS変数名を直接書けました。v4は括弧を丸括弧に変えています。両方を同じHTMLに書いて v4.3.3 でビルドすると、違いが一目で分かります。

/* v4.3.3 が実際に出力したCSS */
.bg-\(--brand\) {
  background-color: var(--brand);
}
.bg-\[--brand\] {
  background-color: --brand;
}

旧記法の bg-[--brand] は、v4では「--brand という名前の任意値」として素直に解釈され、background-color: --brand; という無効な宣言になります。クラスは生成されるのでビルドは成功し、CSSファイルにも行は存在し、ただ背景色だけが付きません。アップグレードツールはこの書き換えを自動化しますが、文字列連結でクラス名を組み立てている箇所は拾えないので、-[-- をリポジトリ全体でgrepして潰すのが確実です。

任意値のカンマ変換廃止とアンダースコアへの移行

v3は grid-cols-*・grid-rows-*・object-* の任意値に限り、カンマを空白へ置き換えていました。v2との互換のための特別扱いで、v4では無くなっています。

/* v4.3.3 が実際に出力したCSS */
.grid-cols-\[max-content\,auto\] {
  grid-template-columns: max-content,auto;
}

カンマがそのまま残り、grid-template-columns としては解釈できない値になります。空白はアンダースコアで表すのが v4 の書き方なので、grid-cols-[max-content_auto] に直します。

非推奨クラスの公式記載とv4.3.3での出力差

v4.3.3 で実際にビルドして、削除対象とされるクラスの出力可否を確かめました。結果は割れます。

透明度系の *-opacity-* は本当に消えており、該当クラスはCSSに1行も現れません。一方、公式ガイドが同じ「削除された非推奨ユーティリティ」の表に並べている flex-shrink-0 や overflow-ellipsis は、v4.3.3 では依然としてCSSが生成されます。「ドキュメント上は削除、実装上は動く」という状態なので、動作確認では移行漏れを検出できません。将来のマイナー版で本当に落ちる可能性を考えるなら、目視ではなくgrepで機械的に洗い出して置換しておくのが安全です。

移行手順：アップグレードツールで済む範囲と手作業の範囲

アップグレードツールの実行条件と処理範囲

公式のアップグレードツールは、依存関係の更新・設定ファイルのCSSへの移行・テンプレート内のクラス書き換えまでをまとめて実行します。

npx @tailwindcss/upgrade

前提は Node.js 20以上です。ガイドは「新しいブランチで実行し、差分を丁寧にレビューしてブラウザで動作確認すること」を明示的に勧めています。パッケージ版は本体と揃っており、2026年9月23日時点で 4.3.3 です。前章のクラス名変更や記法変更の大半はここで自動処理されるので、手で直し始める前に一度流してください。

自動移行後に必要な手動確認

自動化の外に残るのは、機械的な文字列置換では判断できない箇所です。

• コンポーネント内の @apply。Vue・Svelte・Astro の <style> ブロックやCSS Modulesのように、メインのCSSとは別にバンドルされるスタイルシートからは、テーマ変数やカスタムユーティリティが見えなくなりました。ファイル先頭に @reference "../../app.css"; を足すか、@apply をやめて var(--color-red-500) を直接書きます。後者のほうが処理が減る分だけ速くなります。
• バリアントの積み順。v3は右から左へ適用していたものが、v4は左から右になりました。first:*:pt-0 は *:first:pt-0 に反転します。影響する代表例は直下の子バリアント * やTypographyプラグインのバリアントを他と積んでいる箇所であり、順序に意味がある組み合わせ全般を確認する必要がありますが、該当数はふつう多くありません。
• important修飾子の位置。!flex ではなく flex! と末尾に置く形に変わりました。旧形式も互換で動きますが非推奨です。
• プレフィックス。v3の tw-flex のような接頭辞は、v4ではバリアントのように先頭へ付けて tw:flex と書きます。読み込みも @import "tailwindcss" prefix(tw); に変わります。
• タッチ端末のhover。v4の hover は @media (hover: hover) で包まれ、ホバーできる入力機器のときだけ効きます。タップでhoverが発火する前提で作っていた画面は動かなくなります。旧挙動が必要なら @custom-variant hover (&:hover); で上書きできますが、公式はhoverを必須機能にしない設計を推奨しています。
• CSSプリプロセッサ。ガイドは「not designed to be used with CSS preprocessors like Sass, Less, or Stylus」と書いています。これは設定の問題ではなく設計方針なので、Sass依存が深いプロジェクトはv4移行そのものを見送る判断もあります。

transform-none でスケールや回転をリセットしていた箇所も要注意です。v4の rotate-*・scale-*・translate-* は個別のCSSプロパティに対応づけられたので、リセットは scale-none のように個別に書きます。

自動ソース検出でクラスが消える条件

v4は既定でクラスを自動検出するため、通常は content 配列が不要です。ただし、@config で読み込む旧JavaScript設定の content は引き続き利用できます。書く量は減りますが、「なぜかクラスが効かない」の原因がここに移りました。挙動を実測で確かめたものを挙げます。

.gitignoreによる既定の走査対象除外

CSSと同階層に index.html（p-1 を含む）と ignored.html（z-50 を含む）を置き、.gitignore に ignored.html だけを書いてビルドしたところ、出力CSSに .p-1 は含まれ z-50 は1行も現れませんでした。ビルド成果物ディレクトリや、生成物としてgit管理外に置いているテンプレートを走査させたい場合は、明示的に @source で足す必要があります。

自動ソース検出の起点と再帰走査

走査の起点はCSSファイルの置き場所ではなく、ビルドを実行したときの作業ディレクトリです。入力CSSのパスを固定したまま作業ディレクトリだけを変えて v4.3.3 でビルドすると、出力に含まれるクラスは作業ディレクトリ配下のものへ入れ替わりました。CSSと同じ階層に置いたHTMLのクラスも、作業ディレクトリが別の場所なら拾われません。npm scripts の実行位置が変わっただけでクラスが消えるのは、この挙動が原因です。

起点から下はサブディレクトリを再帰的に走査します。sub/a.html（z-40）と sub/deeper/b.html（tracking-widest）を置いた状態でビルドすると、どちらのクラスも出力に含まれました。階層の深さに制限はないため、モノレポや検証用の別プロジェクトを同じツリーに置いている構成では、意図しないクラスまで拾われてCSSが膨らみます。

起点を作業ディレクトリ任せにしたくない場合は、読み込み時に指定できます。@import "tailwindcss" source("./app"); と書いて同じ検証を繰り返すと、作業ディレクトリに関係なく app/ 配下のクラスだけが出力されました。

@sourceによる走査対象の追加・除外とクラスの明示生成

いずれも実測した挙動です。

@import "tailwindcss";
@source not "./sub";
@source inline("bg-lime-{200,400}");

この設定でビルドすると、sub/ 以下のクラス（z-40・tracking-widest）は出力から消え、代わりにHTMLのどこにも書いていない .bg-lime-200 と .bg-lime-400 が生成されました。@source inline() は波括弧の展開に対応しているので、v3の safelist で列挙していたクラス群をまとめて指定できます。前述のとおりこの2つは v4.1.0 からの機能です。

v4.0のあとに増えた機能（v4.1・v4.2・v4.3）

日本語で出回っている移行記事の多くは2025年初頭に書かれており、v4.0時点で記述が止まっています。実際にはその後3つのマイナー版が出ているので、いま移行するなら前提が違います。

v4.1の追加機能：テキストシャドウ・マスク・ソース指定

影とマスクが入った版です。text-shadow-* と mask-* 系ユーティリティが追加され、テキストの影をユーティリティで書けるようになりました。あわせて wrap-anywhere・wrap-break-word による折り返し制御、入力機器を判定する pointer-* と any-pointer-*、フォーム検証用の user-valid・user-invalid、noscript、inverted-colors、details-content の各バリアントが増えています。前章で触れた @source inline() と @source not "…" もこの版です。

v4.2の追加機能：論理プロパティ・webpack・新パレット

論理プロパティを一気に埋めた版です。pbs-*・pbe-*・mbs-*・mbe-*・inline-*・block-*・inset-s-*・inset-e-* などが追加され、あわせて start-* と end-* が非推奨になりました。@tailwindcss/webpack パッケージと font-features-*、mauve・olive・mist・taupe の4パレットもこの版です。

公式ブログにv4.2単独の告知記事は無く、これらの追加はv4.3の告知記事にまとめて紹介されています。どの機能がどの版から使えるかを確認するときは、ブログではなく GitHubのリリースノートを見てください。

v4.3の追加機能：スクロールバー・サイズコンテナ・@variant

スクロールバー関連が中心です。scrollbar-{auto,thin,none}、scrollbar-thumb-*・scrollbar-track-* の色指定、scrollbar-gutter-* が追加されました。ほかに zoom-*、tab-*、コンテナに container-type: size を当てる @container-size、@variant での積み重ね（@variant hover:focus）と複合（@variant hover, focus）の指定が入っています。

v3のまま運用するか、v4へ上げるかの判断

新規プロジェクトは対応ブラウザと依存ツールの条件を満たすならv4を第一候補とし、既存プロジェクトは互換性と移行工数で判断します。

まず前提として、v3は終了していません。npmの tailwindcss パッケージには v3-lts という dist-tag があり、その参照先は 3.4.19（2025年12月10日公開）です。v4.0が出た2025年1月以降にも 3.4.18（2025年10月1日）と 3.4.19 が公開されており、v3系に保守リリースが続いていることが npm registry の公開日から確認できます。「v4が出た＝v3が即座に切られた」ではありません。

据え置きを選ぶ理由になるのは次の条件です。Safari 16.4 未満・Chrome 111 未満を公式サポート対象に含んでいる。Sass や Less に依存したスタイル資産が大きく、外す工数が見積もれない。デザインシステムを @layer components で組んでおり、@utility への書き換えと詳細度の再設計に手が回らない。いずれかに当たるなら、無理に上げるより v3.4.19 に固定して次の改修サイクルで検討するほうが安全です。

コンテナクエリの本体統合や上限側のバリアントを使いたい場合は、v4への移行が候補になります。v3.4.19 で @container と @md:flex を含むHTMLをビルドしても、コンテナクエリ関連のCSSは1行も生成されません。v3では @tailwindcss/container-queries プラグインが別途必要で、そのパッケージは 0.1.1（2023年3月31日公開）が最後のリリースです。v4.3.3 は素の状態で次を出力します。

/* v4.3.3 が @container / @md:flex / @max-lg:block から出力したCSS */
.\@container { container-type: inline-size; }

@container (width >= 28rem) {
  .\@md\:flex { display: flex; }
}
@container (width < 32rem) {
  .\@max-lg\:block { display: block; }
}

@max-* による上限側の指定もプラグイン無しで書けます。レスポンシブをビューポート幅ではなく親要素の幅で切りたい設計なら、この一点だけでもv4へ上げる価値があります。

よくある質問

Tailwind CSSの最新バージョンはいくつですか？

2026年9月23日時点で npm の latest は 4.3.3 です（2026年7月16日公開）。v4系のマイナー版は 4.0（2025年1月22日）・4.1（2025年4月1日）・4.2（2026年2月18日）・4.3（2026年5月8日）の4つです。v3系は v3-lts タグで 3.4.19 が参照されています。

Tailwind CSS v5はリリースされていますか？

されていません。npm registry に 5.x 系のバージョンは1つも公開されておらず、latest は 4.3.3 のままです。版番号を調べる際は、Tailwind CSS本体と、daisyUIなど周辺ライブラリの版番号を区別してください。

コンテナクエリの書き方はv3とv4でどう変わりましたか？

v3では @tailwindcss/container-queries プラグインの導入が必要でしたが、v4は本体に入っています。親に @container を付け、子に @md:flex のように指定すると @container (width >= 28rem) が出力されます。上限側は @max-lg:block で @container (width < 32rem) になります。v4.3では container-type: size を当てる @container-size も追加されました。

tailwind.config.js はv4でも使えますか？

使えますが自動では読み込まれません。CSSに @config "../../tailwind.config.js"; と書いて明示的に指定します。ただし corePlugins・safelist・separator の3オプションはv4で非対応です。safelist は @source inline()（v4.1以降）に置き換えます。

v3からv4に上げたとき、どこから見た目が崩れやすいですか？

影・角丸・ぼかしの名前がずれた箇所（shadow-sm・rounded-sm・blur-sm）、色を指定していない border（gray-200からcurrentColorへ）、ring（3pxから1pxへ、既定色もcurrentColorへ）、focus:outline-none（アウトラインが本当に消える）の4か所です。いずれもクラス名がv4でも有効なためビルドは成功します。アップグレードツールを流したあと、この4種類をgrepで数えてから目視確認する手順が効率的です。

関連記事

• Tailwind Variants(tv)の使い方｜slots・compoundVariants・レスポンシブとTailwind CSS v4対応
• Tailwind CSSとEmotionの違い｜v4での使い分けと共存
• daisyUIとは？Tailwind CSSコンポーネントの使い方とv5の設定変更【2026年版】
• UnoCSSとは？アトミックCSSエンジンの設定と採用判断を実装目線で解説
• NativeWindとは？Tailwind CSSをReact Nativeで使うための統合ライブラリを解説