Upgrading from v3 to v4#

If you’re coming from Django-Tailwind 3.x, your Tailwind CSS project probably depends on Tailwind CSS 3.x. If you want to use latest features of the version 4.x, you need to upgrade your Tailwind CSS app from 3.x to 4.

In the following instructions, I assume that your Tailwind CSS app name is set as TAILWIND_APP_NAME = 'theme' in settings.py.

If it’s different for you, please replace the theme with an app name of your choice, while following my steps.

Tip

These instructions are for installations where the 3.x configuration was modified in tailwind.config.js. If your installation has not modified this file at all, then you can just delete the theme app and follow the Installation instructions. Once that is complete, follow the Taiwind Upgrade Guide.

Note

Tailwind 4 has many class changes (renamed or depreciated). Once you have upgrade to the Tailwind 4, you will want to go through the Taiwind Upgrade Guide to see how to update your classes.

Caution

As with all changes of this nature, you should be working in a clean branch and then verify all changes made before merging!

Option 1: The Easy Way#

Tailwind 4 is able to use the legacy JavaScript-based configuration file that is used in Tailwind 3. If you do not want to migrate your configuration to the new method, then follow the steps below.

Note

The corePlugins, safelist and separator options from the JavaScript-based config are not supported in v4.0.

Rename the theme app so we can install the new version of Tailwind:
```
mv theme theme-backup
```
Follow the Installation steps to install the latest version of Tailwind 4.

Make a copy of tailwind.config.js to the new theme app:

cp theme-backup/static_src/tailwind.config.js theme/static_src/

Update the Tailwind configuration in theme/static_src/src/styles.css:

- @import "tailwindcss" source("../../../");

+ @import "tailwindcss" source(none);
+ @config "../tailwind.config.js";

You can now run the tailwind server:
```
python manage.py tailwind start
```
If everything is working as expected, then you can delete theme-backup
```
rm -rf theme-backup
```

Option 2: Migrate the Configuration#

Tailwind has provided a migration tool to convert the Javascript-based configuration file to the new Function and Directive style configuration. This can save a lot of time, however tat the time of writing, there are still a few bugs to navigate.

Navigate to the static_src directory:
```
cd theme/static_src
```
Run the `Tailwind Upgrade Utility.
```
npx @tailwindcss/upgrade@next
```

Rename the theme app so we can install the new version of Tailwind to ensure you are using django-tailwind-4:
```
cd ../../
mv theme theme-backup
```
Follow the Installation steps to install the latest version of Tailwind 4 from the maintained django-tailwind-4 project.
Rename the theme/static_src/src/styles.css file so you still have it as a reference:
```
mv theme/static_src/src/styles.css theme/static_src/src/styless.css.backup
```
Copy the styles.css file that was generated by the Tailwind Upgrade utility:
```
cp theme-backup/static_src/src/styles.css theme/static_src/src/
```
View the styles.css file and make sure that the configuration migrated ok.

Note

The utility may have added some configuration that is not needed anymore, for example picking up additional folders to watch via the @source directive. If you do not need any specific configuration, you can remove this and include all folders like the configuration in styles.css.backup. If you had plugins installed in your old configuration, you can add them in to the new configuration like in styles.backup.css.

You can now run the tailwind server:
```
python manage.py tailwind start
```
If everything is working as expected, then you can delete theme-backup and styles.css.backup:
```
rm -rf theme-backup theme/static_src/src/styless.css.backup
```

And that’s it. You’re now on the latest Django-Tailwind-4 4.0 with the latest Tailwind CSS 4.0 installed and ready to go.