Import/Migrate K2 articles with videos, galleries and downloads from Joomla 3 to Joomla 4


This article describes a procedure for importing larger Joomla3 websites that run with the K2 article system into a Joomla4 system. The basic handling of Joomla, extensions, fields and overrides, databases, PhpMyAdmin and PHP is assumed and is not described here.

Please note:

Be sure to perfom the migration in a test environment!

These instructions describe a procedure that has worked well for me on many occasions. But this is no guarantee that it will work for everyone else. The implementation is therefore at your own risk and without any guarantee, warranty or support.

Backup the website after each step!

I have had good experiences with Akeeba Backup for backing up and restoring data. The individual migration steps depend on how many articles are available in K2 and whether the image gallery, video, attachment and extra fields tabs were used.

Migration steps:

  1. Preparation: Export article list J3/K2
    For this I use a module override (mod_custom) in the admin area on the dashboard, which outputs a tabular overview of all articles including categories, image galleries, videos, downloads and extra fields in the dashboard. I copy this table into an Excel file.
    Download mod_custom articlelistk2.php
    Unzip the file and copy it to /administrator/templates/yourAdminTemplate/html/mod_custom.
    Before exporting and migrating, it makes sense to delete all deactivated and trashed items!
  2. Import articles from K2 into J3 posts, including extra fields
    For this I use the extension k2-to-com-content-migration from Joomlart.
  3. Save folder /media/k2 if necessary. This is important because this folder will be deleted once you uninstall K2.
    1. Back up video folder
      If there is content in the /media/k2/videos folder, save it offline first.
    2. Back up gallery folders
      Image galleries that have been entered into K2 are now located in the /images/joomlart folder in subdirectories with the corresponding ID of the K2 article. However, not all images may be adopted. So I move the original directories from /media/k2/galleries to another folder, e.g. /images/galleries
    3. Back up attachment folders
      First save the /media/k2/attachments folder offline.
  4. Change menu items from K2 to Joomla items
    I'm not creating any template overrides here yet, as they may need to be adjusted again in Joomla 4.
  5. Check installed extensions for J4 suitability using the Joomla update button
    1. Perform backup
    2. Uninstall all non-Joomla4 compatible extensions
  6. Perform upgrade to Joomla 4
    1. Perform backup
    2. Perform upgrade
  7. Joomla 4 - Check installation, install components if necessary (language, Akeeba)
  8. Check template, if necessary switch to Cassiopeia

For websites without filled K2 tabs (image gallery, video and attachment), the migration would now be complete and template adjustments/overrides can be made. Otherwise the migration continues as follows:

  1. The appropriate extensions should now be available for the desired fields:
    1. Video: Install the AllVideo-Plugin extension if it is no longer available.
    2. Image galleries: To import the old image galleries from K2, I used either the Simple Image Gallery Free plugin from Joomla Works or Simple Image Gallery Extended Pro from Kubik Rubik.
      Both use the same tags, but SIGE has more setting options.
      For new galleries I use the
      Advanced Custom Fields extension from Tassos Marinos. To me this much more comfortable to use (setting options, manual sorting of the images, etc.).
    3. Attachments / Downloads: The Advanced Custom Fields extension is also the right tool for this.
  2.  Create fields:
    1. Video -> Textarea
    2. Gallerie:
      Imported Gallery -> Textarea
      New Gallery -> ACF Gallery
    3. Attachments / Downloads -> ACF Fileupload

Depending on the scope of the fields to be imported, you can now manually copy the fields in the individual posts with the data from the Excel table (point 1).

  • The video and gallery tags from the table are copied into the corresponding fields in the post. Please make sure that the paths are correct: {gallery}75{/gallery} can then become {gallery}pathtogallery/75{/gallery}.
  • The downloads will be uploaded accordingly to the corresponding field in the post.

In my experience, you can use this manual method for up to 50 items. If there are more articles that need to be processed manually, it is a good idea to import the fields using an SQL script. PhpMyAdmin access is an advantage  for this.

  1. Preparations:
    1. Move videos to the appropriate folder (see AllVideoPlugin setting)
    2. Image gallery: Check whether the galleries are in the folders according to the tags
    3. Attachments / Downloads: Move to the /media/acfupload folder.
  2. Create CSV import lists:
    Since the article IDs are reassigned during import, a table now has to be generated in which the new article IDs with the associated videos, galleries and downloads are located. I solved this with an Excel sheet of the imported posts and the Excel function VLOOKUP. The goal is to end up with 3 CSV tables with the following columns. I marked the columns with | separated because semicolons were used occasionally in the download file names..
    1. Video: Column 1 -> field-ID,  Column 2 -> new item-ID, column 3-> video tag (example: {mp4}pathtovideo/xx{/mp4})
    2. Gallery: Column 1 -> field-ID,  Column 2 -> new item-ID, column 3 -> gallery tag (example: {gallery}pathtogallery/75{/gallery})
    3. Attachments / Downloads: Column 1 -> new item-ID, column 2 -> file name (example: xxx.pdf)
      It is important here that all files are listed individually if there are several downloads per post
  3. Import script
    I wrote a small script on my server that reads the respective CSV file and outputs an SQL string. I then copy this into the _fields_values table of the Joomla database via PhpMyAdmin. Please be sure to save the relevant table beforehand!
    The scripts can be downloaded as a zip file here.
    1. Import video and galleries:
      The CSV files can be imported into the _fields_values table via PhpMyAdmin.
      Alternatively, the script can also be used to generate an SQL string

      script gallery video
    2. Script for attachments/downloads
      script download

Now all videos, image galleries and downloads should be visible in the new posts. Outputs can be controlled with field settings and template overrides.