diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 07fb8285..3822e414 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -32,7 +32,7 @@ jobs:
       - name: Run tests
         run: bin/test
 
-  user-journey:
+  user-install:
     strategy:
       fail-fast: false
       matrix:
@@ -44,5 +44,20 @@ jobs:
         with:
           ruby-version: "3.4"
           bundler: latest
-      - run: test/integration/user_journey_test.sh
+      - run: test/integration/user_install_test.sh
+        shell: bash
+
+  user-upgrade:
+    strategy:
+      fail-fast: false
+      matrix:
+        plat: ["ubuntu", "macos"] # TODO: on windows the tailwind upgrader tests are failing
+    runs-on: ${{matrix.plat}}-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler: latest
+      - run: test/integration/user_upgrade_test.sh
         shell: bash
diff --git a/.github/workflows/upstream.yml b/.github/workflows/upstream.yml
index e491a957..e1b12dea 100644
--- a/.github/workflows/upstream.yml
+++ b/.github/workflows/upstream.yml
@@ -34,8 +34,8 @@ jobs:
       - name: Run tests
         run: bin/test
 
-  user-journey:
-    name: "user-journey (rails ${{ matrix.ref }})"
+  user-install:
+    name: "user-install (rails ${{ matrix.ref }})"
     runs-on: ${{matrix.plat}}-latest
     strategy:
       fail-fast: false
@@ -50,5 +50,24 @@ jobs:
         with:
           ruby-version: "3.3"
           bundler: latest
-      - run: test/integration/user_journey_test.sh
+      - run: test/integration/user_install_test.sh
+        shell: bash
+
+  user-upgrade:
+    name: "user-upgrade (rails ${{ matrix.ref }})"
+    runs-on: ${{matrix.plat}}-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        plat: ["ubuntu"]
+        ref: ["7-2-stable", "8-0-stable", "main"]
+    env:
+      RAILSOPTS: --git=https://github.com/rails/rails --ref=${{ matrix.ref }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+          bundler: latest
+      - run: test/integration/user_upgrade_test.sh
         shell: bash
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a4040dfa..c2e8746f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -9,7 +9,7 @@ This doc is a brief introduction on modifying and maintaining this gem.
 
 The unit tests are run with `bundle exec rake test`
 
-There is an additional integration test which runs in CI, `test/integration/user_journey_test.sh` which you may also want to run.
+There is an additional integration test which runs in CI, `test/integration/user_install_test.sh` which you may also want to run.
 
 
 ### Testing in a Rails app
diff --git a/lib/install/tailwindcss.rb b/lib/install/install_tailwindcss.rb
similarity index 100%
rename from lib/install/tailwindcss.rb
rename to lib/install/install_tailwindcss.rb
diff --git a/lib/install/upgrade_tailwindcss.rb b/lib/install/upgrade_tailwindcss.rb
new file mode 100644
index 00000000..b5389c73
--- /dev/null
+++ b/lib/install/upgrade_tailwindcss.rb
@@ -0,0 +1,48 @@
+TAILWIND_CONFIG_PATH = Rails.root.join("config/tailwind.config.js")
+APPLICATION_LAYOUT_PATH = Rails.root.join("app/views/layouts/application.html.erb")
+POSTCSS_CONFIG_PATH = Rails.root.join("config/postcss.config.js")
+
+unless TAILWIND_CONFIG_PATH.exist?
+  say "Default tailwind.config.js is missing!", :red
+  abort
+end
+
+if File.read(TAILWIND_CONFIG_PATH).match?(/defaultTheme/)
+  say "Removing references to 'defaultTheme' from #{TAILWIND_CONFIG_PATH}"
+  gsub_file TAILWIND_CONFIG_PATH.to_s, /^(.*defaultTheme)/, "// \\1"
+end
+
+if POSTCSS_CONFIG_PATH.exist?
+  say "Moving PostCSS configuration to application root directory"
+  FileUtils.mv(POSTCSS_CONFIG_PATH, Rails.root, verbose: true) || abort
+end
+
+if system("npx --version")
+  say "Running the upstream Tailwind CSS upgrader"
+  command = Shellwords.join(["npx", "@tailwindcss/upgrade@next", "--force", "--config", TAILWIND_CONFIG_PATH.to_s])
+  success = run(command, abort_on_failure: false)
+  unless success
+    say "The upgrade tool failed!", :red
+    say %(        You probably need to update your configuration. Please read the error messages,)
+    say %(        and check the Tailwind CSS upgrade guide at https://tailwindcss.com/docs/upgrade-guide.)
+    abort
+  end
+else
+  say "Could not run the Tailwind upgrade tool. Please see https://tailwindcss.com/docs/upgrade-guide for manual instructions.", :red
+  abort
+end
+
+if APPLICATION_LAYOUT_PATH.exist?
+  if File.read(APPLICATION_LAYOUT_PATH).match?(/"inter-font"/)
+    say "Strip Inter font CSS from application layout"
+    gsub_file APPLICATION_LAYOUT_PATH.to_s, %r{, "inter-font"}, ""
+  else
+    say "Inter font CSS not detected.", :green
+  end
+else
+  say "Default application.html.erb is missing!", :red
+  say %(        Please check your layouts and remove any "inter-font" stylesheet links.)
+end
+
+say "Compile initial Tailwind build"
+run "rails tailwindcss:build"
diff --git a/lib/tasks/install.rake b/lib/tasks/install.rake
index 2a571cad..f94ec2a1 100644
--- a/lib/tasks/install.rake
+++ b/lib/tasks/install.rake
@@ -1,6 +1,6 @@
 namespace :tailwindcss do
   desc "Install Tailwind CSS into the app"
   task :install do
-    system "#{RbConfig.ruby} ./bin/rails app:template LOCATION=#{File.expand_path("../install/tailwindcss.rb", __dir__)}"
+    system "#{RbConfig.ruby} ./bin/rails app:template LOCATION=#{File.expand_path("../install/install_tailwindcss.rb", __dir__)}"
   end
 end
diff --git a/lib/tasks/upgrade.rake b/lib/tasks/upgrade.rake
new file mode 100644
index 00000000..05047523
--- /dev/null
+++ b/lib/tasks/upgrade.rake
@@ -0,0 +1,6 @@
+namespace :tailwindcss do
+  desc "Upgrade app from Tailwind CSS v3 to v4"
+  task :upgrade do
+    system "#{RbConfig.ruby} ./bin/rails app:template LOCATION=#{File.expand_path("../install/upgrade_tailwindcss.rb", __dir__)}"
+  end
+end
diff --git a/test/integration/user_journey_test.sh b/test/integration/user_install_test.sh
similarity index 96%
rename from test/integration/user_journey_test.sh
rename to test/integration/user_install_test.sh
index 985b72c4..dd36af25 100755
--- a/test/integration/user_journey_test.sh
+++ b/test/integration/user_install_test.sh
@@ -18,8 +18,8 @@ pushd "My Workspace"
 
 # create a rails app
 bundle exec rails -v
-bundle exec rails new test-app --skip-bundle
-pushd test-app
+bundle exec rails new test-install --skip-bundle
+pushd test-install
 
 # make sure to use the same version of rails (e.g., install from git source if necessary)
 bundle remove rails --skip-install
diff --git a/test/integration/user_upgrade_test.sh b/test/integration/user_upgrade_test.sh
new file mode 100755
index 00000000..e4912818
--- /dev/null
+++ b/test/integration/user_upgrade_test.sh
@@ -0,0 +1,87 @@
+#! /usr/bin/env bash
+# reproduce the documented user journey for installing and running tailwindcss-rails
+# this is run in the CI pipeline, non-zero exit code indicates a failure
+
+set -o pipefail
+set -eux
+
+# set up dependencies
+rm -f Gemfile.lock
+bundle remove actionmailer
+bundle add rails --skip-install ${RAILSOPTS:-}
+bundle install --prefer-local
+
+# do our work a directory with spaces in the name (#176, #184)
+rm -rf "My Workspace"
+mkdir "My Workspace"
+pushd "My Workspace"
+
+# create a rails app
+bundle exec rails -v
+bundle exec rails new test-upgrade --skip-bundle
+pushd test-upgrade
+
+# make sure to use the same version of rails (e.g., install from git source if necessary)
+bundle remove rails --skip-install
+bundle add rails --skip-install ${RAILSOPTS:-}
+
+# set up app with tailwindcss-rails v3 and tailwindcss-ruby v3
+bundle add tailwindcss-rails --skip-install --version 3.3.0
+bundle add tailwindcss-ruby  --skip-install --version 3.4.17
+bundle install --prefer-local
+bundle show --paths
+bundle binstubs --all
+
+# install tailwindcss
+bin/rails tailwindcss:install
+grep -q inter-font app/views/layouts/application.html.erb
+
+if [[ $(rails -v) > "Rails 8.0.0.beta" ]] ; then
+  # install auth templates
+  bin/rails generate authentication
+  grep -q PasswordsController app/controllers/passwords_controller.rb
+fi
+
+# install scaffold templates
+bin/rails generate scaffold post title:string body:text published:boolean
+grep -q "Show this post" app/views/posts/index.html.erb
+
+# upgrade time!
+bundle remove tailwindcss-rails --skip-install
+bundle remove tailwindcss-ruby --skip-install
+
+bundle add tailwindcss-rails --skip-install --path="../.."
+bundle add tailwindcss-ruby  --skip-install --version 4.0.0
+
+bundle install --prefer-local
+bundle show --paths
+bundle binstubs --all
+
+# create a postcss file
+cat <<EOF > config/postcss.config.js
+module.exports = {
+  plugins: {
+    autoprefixer: {},
+  },
+}
+EOF
+
+bin/rails tailwindcss:upgrade
+
+# TEST: removal of inter-font CSS
+if grep -q inter-font app/views/layouts/application.html.erb ; then
+  echo "FAIL: inter-font CSS not removed"
+  exit 1
+fi
+
+# TEST: moving the postcss file
+if [ ! -f postcss.config.js ] ; then
+  echo "FAIL: postcss.config.js not moved"
+  exit 1
+fi
+
+# generate CSS
+bin/rails tailwindcss:build[verbose]
+grep -q "py-2" app/assets/builds/tailwind.css
+
+echo "OK"