Show version mismatch when running upgrade tool

.github/workflows/integration-tests.yml

@@ -53,6 +53,10 @@ jobs:
       - uses: actions/checkout@v4
       - uses: pnpm/action-setup@v4
 
+      - run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
       - name: Use Node.js ${{ matrix.node-version }}
         uses: actions/setup-node@v4
         with:

CHANGELOG.md

@@ -27,6 +27,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Detect classes in markdown inline directives ([#18967](https://github.com/tailwindlabs/tailwindcss/pull/18967))
 - Ensure files with only `@theme` produce no output when built ([#18979](https://github.com/tailwindlabs/tailwindcss/pull/18979))
 - Support Maud templates when extracting classes ([#18988](https://github.com/tailwindlabs/tailwindcss/pull/18988))
+- Show version mismatch (if any) when running upgrade tool ([#19028](https://github.com/tailwindlabs/tailwindcss/pull/19028))
 
 ## [4.1.13] - 2025-09-03
 

integrations/upgrade/upgrade-errors.test.ts

@@ -0,0 +1,227 @@
+import { stripVTControlCharacters } from 'node:util'
+// @ts-expect-error This path does exist
+import { version } from '../../packages/tailwindcss/package.json'
+import { css, html, js, json, test } from '../utils'
+
+test(
+  'upgrades half-upgraded v3 project to v4 (pnpm)',
+  {
+    fs: {
+      'package.json': json`
+        {
+          "dependencies": {
+            "tailwindcss": "^3",
+            "@tailwindcss/upgrade": "workspace:^"
+          },
+          "devDependencies": {
+            "@tailwindcss/cli": "workspace:^"
+          }
+        }
+      `,
+      'tailwind.config.js': js`
+        /** @type {import('tailwindcss').Config} */
+        module.exports = {
+          content: ['./src/**/*.{html,js}'],
+        }
+      `,
+      'src/index.html': html`
+        <div class="!flex">Hello World</div>
+      `,
+      'src/input.css': css`
+        @tailwind base;
+        @tailwind components;
+        @tailwind utilities;
+      `,
+    },
+  },
+  async ({ exec, expect }) => {
+    // Ensure we are in a git repo
+    await exec('git init')
+    await exec('git add --all')
+    await exec('git commit -m "before migration"')
+
+    // Fully upgrade to v4
+    await exec('npx @tailwindcss/upgrade')
+
+    // Undo all changes to the current repo. This will bring the repo back to a
+    // v3 state, but the `node_modules` will now have v4 installed.
+    await exec('git reset --hard HEAD')
+
+    // Re-running the upgrade should result in an error
+    return expect(() => {
+      return exec('npx @tailwindcss/upgrade', {}, { ignoreStdErr: true }).catch((e) => {
+        // Replacing the current version with a hardcoded `v4` to make it stable
+        // when we release new minor/patch versions.
+        return Promise.reject(stripVTControlCharacters(e.message.replaceAll(version, '4.0.0')))
+      })
+    }).rejects.toThrowErrorMatchingInlineSnapshot(`
+      "Command failed: npx @tailwindcss/upgrade
+      ≈ tailwindcss v4.0.0
+
+      │ ↳ Upgrading from Tailwind CSS \`v4.0.0\` 
+
+      │ ↳ Version mismatch 
+      │    
+      │   \`\`\`diff 
+      │   - "tailwindcss": "^3" (expected version in package.json / lockfile) 
+      │   + "tailwindcss": "4.0.0" (installed version in \`node_modules\`) 
+      │   \`\`\` 
+      │    
+      │   Make sure to run \`pnpm install\`, and try again. 
+
+      "
+    `)
+  },
+)
+
+test(
+  'upgrades half-upgraded v3 project to v4 (bun)',
+  {
+    fs: {
+      'package.json': json`
+        {
+          "dependencies": {
+            "tailwindcss": "^3",
+            "@tailwindcss/upgrade": "workspace:^"
+          },
+          "devDependencies": {
+            "@tailwindcss/cli": "workspace:^",
+            "bun": "^1.0.0"
+          }
+        }
+      `,
+      'tailwind.config.js': js`
+        /** @type {import('tailwindcss').Config} */
+        module.exports = {
+          content: ['./src/**/*.{html,js}'],
+        }
+      `,
+      'src/index.html': html`
+        <div class="!flex">Hello World</div>
+      `,
+      'src/input.css': css`
+        @tailwind base;
+        @tailwind components;
+        @tailwind utilities;
+      `,
+    },
+  },
+  async ({ exec, expect }) => {
+    // Use `bun` to install dependencies
+    await exec('rm ./pnpm-lock.yaml')
+    await exec('npx bun install')
+
+    // Ensure we are in a git repo
+    await exec('git init')
+    await exec('git add --all')
+    await exec('git commit -m "before migration"')
+
+    // Fully upgrade to v4
+    await exec('npx @tailwindcss/upgrade')
+
+    // Undo all changes to the current repo. This will bring the repo back to a
+    // v3 state, but the `node_modules` will now have v4 installed.
+    await exec('git reset --hard HEAD')
+
+    // Re-running the upgrade should result in an error
+    return expect(() => {
+      return exec('npx @tailwindcss/upgrade', {}, { ignoreStdErr: true }).catch((e) => {
+        // Replacing the current version with a hardcoded `v4` to make it stable
+        // when we release new minor/patch versions.
+        return Promise.reject(stripVTControlCharacters(e.message.replaceAll(version, '4.0.0')))
+      })
+    }).rejects.toThrowErrorMatchingInlineSnapshot(`
+      "Command failed: npx @tailwindcss/upgrade
+      ≈ tailwindcss v4.0.0
+
+      │ ↳ Upgrading from Tailwind CSS \`v4.0.0\` 
+
+      │ ↳ Version mismatch 
+      │    
+      │   \`\`\`diff 
+      │   - "tailwindcss": "^3" (expected version in package.json / lockfile) 
+      │   + "tailwindcss": "4.0.0" (installed version in \`node_modules\`) 
+      │   \`\`\` 
+      │    
+      │   Make sure to run \`bun install\`, and try again. 
+
+      "
+    `)
+  },
+)
+
+test(
+  'upgrades half-upgraded v3 project to v4 (npm)',
+  {
+    fs: {
+      'package.json': json`
+        {
+          "dependencies": {
+            "tailwindcss": "^3",
+            "@tailwindcss/upgrade": "workspace:^"
+          },
+          "devDependencies": {
+            "@tailwindcss/cli": "workspace:^"
+          }
+        }
+      `,
+      'tailwind.config.js': js`
+        /** @type {import('tailwindcss').Config} */
+        module.exports = {
+          content: ['./src/**/*.{html,js}'],
+        }
+      `,
+      'src/index.html': html`
+        <div class="!flex">Hello World</div>
+      `,
+      'src/input.css': css`
+        @tailwind base;
+        @tailwind components;
+        @tailwind utilities;
+      `,
+    },
+  },
+  async ({ exec, expect }) => {
+    // Use `bun` to install dependencies
+    await exec('rm ./pnpm-lock.yaml')
+    await exec('rm -rf ./node_modules')
+    await exec('npm install')
+
+    // Ensure we are in a git repo
+    await exec('git init')
+    await exec('git add --all')
+    await exec('git commit -m "before migration"')
+
+    // Fully upgrade to v4
+    await exec('npx @tailwindcss/upgrade')
+
+    // Undo all changes to the current repo. This will bring the repo back to a
+    // v3 state, but the `node_modules` will now have v4 installed.
+    await exec('git reset --hard HEAD')
+
+    // Re-running the upgrade should result in an error
+    return expect(() => {
+      return exec('npx @tailwindcss/upgrade', {}, { ignoreStdErr: true }).catch((e) => {
+        // Replacing the current version with a hardcoded `v4` to make it stable
+        // when we release new minor/patch versions.
+        return Promise.reject(stripVTControlCharacters(e.message.replaceAll(version, '4.0.0')))
+      })
+    }).rejects.toThrowErrorMatchingInlineSnapshot(`
+      "Command failed: npx @tailwindcss/upgrade
+      ≈ tailwindcss v4.0.0
+
+      │ ↳ Upgrading from Tailwind CSS \`v4.0.0\` 
+
+      │ ↳ Version mismatch 
+      │    
+      │   \`\`\`diff 
+      │   - "tailwindcss": "^3" (expected version in package.json / lockfile) 
+      │   + "tailwindcss": "4.0.0" (installed version in \`node_modules\`) 
+      │   \`\`\` 
+      │    
+      │   Make sure to run \`npm install\`, and try again. 
+
+      "
+    `)
+  },
+)

packages/@tailwindcss-upgrade/src/index.ts

@@ -4,6 +4,7 @@ import { Scanner } from '@tailwindcss/oxide'
 import { globby } from 'globby'
 import fs from 'node:fs/promises'
 import path from 'node:path'
+import pc from 'picocolors'
 import postcss from 'postcss'
 import { migrateJsConfig } from './codemods/config/migrate-js-config'
 import { migratePostCSSConfig } from './codemods/config/migrate-postcss'
@@ -62,6 +63,27 @@ async function run() {
     prefix: '↳ ',
   })
 
+  if (version.installedTailwindVersion(base) !== version.expectedTailwindVersion(base)) {
+    let pkgManager = await pkg(base).manager()
+
+    error(
+      [
+        'Version mismatch',
+        '',
+        pc.dim('```diff'),
+        `${pc.red('-')} ${`${pc.dim('"tailwindcss":')} ${`${pc.dim('"')}${pc.blue(version.expectedTailwindVersion(base))}${pc.dim('"')}`}`} (expected version in package.json / lockfile)`,
+        `${pc.green('+')} ${`${pc.dim('"tailwindcss":')} ${`${pc.dim('"')}${pc.blue(version.installedTailwindVersion(base))}${pc.dim('"')}`}`} (installed version in \`node_modules\`)`,
+        pc.dim('```'),
+        '',
+        `Make sure to run ${highlight(`${pkgManager} install`)}, and try again.`,
+      ].join('\n'),
+      {
+        prefix: '↳ ',
+      },
+    )
+    process.exit(1)
+  }
+
   {
     // Stylesheet migrations
 

packages/@tailwindcss-upgrade/src/utils/packages.ts

@@ -24,6 +24,9 @@ const manifests = new DefaultMap((base) => {
 
 export function pkg(base: string) {
   return {
+    async manager() {
+      return await packageManagerForBase.get(base)
+    },
     async add(packages: string[], location: 'dependencies' | 'devDependencies' = 'dependencies') {
       let packageManager = await packageManagerForBase.get(base)
       let args = packages.slice()

packages/@tailwindcss-upgrade/src/utils/renderer.ts

@@ -44,7 +44,7 @@ export function wordWrap(text: string, width: number): string[] {
   // Handle text with newlines by maintaining the newlines, then splitting
   // each line separately.
   if (text.includes('\n')) {
-    return text.split('\n').flatMap((line) => wordWrap(line, width))
+    return text.split('\n').flatMap((line) => (line ? wordWrap(line, width) : ['']))
   }
 
   let words = text.split(' ')

packages/@tailwindcss-upgrade/src/utils/version.ts

@@ -1,3 +1,4 @@
+import { execSync } from 'node:child_process'
 import semver from 'semver'
 import { DefaultMap } from '../../../tailwindcss/src/utils/default-map'
 import { getPackageVersionSync } from './package-version'
@@ -29,3 +30,34 @@ let cache = new DefaultMap((base) => {
 export function installedTailwindVersion(base = process.cwd()): string {
   return cache.get(base)
 }
+
+let expectedCache = new DefaultMap((base) => {
+  try {
+    // This will report a problem if the package.json/package-lock.json
+    // mismatches with the installed version in node_modules.
+    //
+    // Also tested this with Bun and PNPM, both seem to work fine.
+    execSync('npm ls tailwindcss --json', { cwd: base, stdio: 'pipe' })
+    return installedTailwindVersion(base)
+  } catch (_e) {
+    try {
+      let e = _e as { stdout: Buffer }
+      let data = JSON.parse(e.stdout.toString())
+
+      return (
+        // Could be a sub-dependency issue, but we are only interested in
+        // the top-level version mismatch.
+        /"(.*?)" from the root project/.exec(data.dependencies.tailwindcss.invalid)?.[1] ??
+        // Fallback to the installed version
+        installedTailwindVersion(base)
+      )
+    } catch {
+      // We don't know how to verify, so let's just return the installed
+      // version to not block the user.
+      return installedTailwindVersion(base)
+    }
+  }
+})
+export function expectedTailwindVersion(base = process.cwd()): string {
+  return expectedCache.get(base)
+}