OJS Migration Guide: Moving from OJS 2.x to OJS 3.3

Role: Site Administrator
Time: 2–4 hours (depending on database size and number of journals)
Source: OJS 2.4.x (any 2.4 release)
Target: OJS 3.3.0-19 (latest 3.3 series release)

Major version migration

This is a major version migration. The OJS 2.x and OJS 3.x series have fundamentally different database schemas, file structures, and plugin APIs. There is no automatic rollback — a full pre-migration backup is mandatory.

What Changes in OJS 3

Area	OJS 2.x	OJS 3.x
User interface	Smarty-based server-rendered	React-based single-page
Plugin API	Legacy hooks system	PKP-lib hooks + REST API
File storage	Flat-file, submissions/journal_id	Contextual directory tree
Database	MySQL 5.5+	MySQL 8.0+ / PostgreSQL 14+
PHP	5.6 (end of life)	8.1+
Theme system	Individual journal themes	Bootstrap-based parent/child
Workflow	3-stage (submission, review, editing)	4-stage (submission, review, copyediting, production)
DOI plugin	Optional, separate install	Bundled from 3.4+

Pre-Migration Checklist

Migration Steps

Step 1 — Upgrade to the Latest OJS 2.4.x First

Before migrating to OJS 3, ensure you are on the latest OJS 2.4.x release (2.4.8-5 as of 2024). Migration from an older 2.4 release may fail.

# Check your current OJS 2.x version
cat /var/www/html/ojs/dbscripts/xml/version.xml | grep -i release

Step 2 — Install OJS 3.3 on a Separate Directory

Do not overwrite your OJS 2 installation. Install OJS 3.3 alongside it.

cd /var/www/html
wget https://pkp.sfu.ca/software/ojs/download/ojs-3.3.0-19.tar.gz
tar -xzf ojs-3.3.0-19.tar.gz
mv ojs-3.3.0-19 ojs3

Step 3 — Create a New Database for OJS 3

CREATE DATABASE ojs3 CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
GRANT ALL PRIVILEGES ON ojs3.* TO 'ojsuser'@'localhost';
FLUSH PRIVILEGES;

Step 4 — Configure OJS 3

cp /var/www/html/ojs3/config.TEMPLATE.inc.php /var/www/html/ojs3/config.inc.php

Edit config.inc.php:

[database]
driver = mysqli
host = localhost
username = ojsuser
password = yourpassword
name = ojs3

[files]
files_dir = /var/www/ojs3-files

Create the files directory:

mkdir -p /var/www/ojs3-files
chown -R www-data:www-data /var/www/ojs3-files /var/www/html/ojs3

Step 5 — Run the OJS 3 Installer (Fresh Install)

Navigate to https://yoursite.com/ojs3/ in your browser and complete the web installer. This creates an empty OJS 3 database.

important

Use the same administrator email as your OJS 2 installation to avoid user duplication issues.

Step 6 — Import OJS 2 Data into OJS 3

OJS 3 ships with a migration script that reads your OJS 2 database directly:

cd /var/www/html/ojs3
php tools/importExport.php OJS2MigrationPlugin \
  --sourceDBHost=localhost \
  --sourceDBUsername=ojsuser \
  --sourceDBPassword=yourpassword \
  --sourceDBName=ojs2 \
  --sourceFilesDir=/var/www/ojs-files

Long-running process

For large installations (thousands of submissions), this migration script can take 1–3 hours. Run it inside a screen or tmux session to prevent SSH disconnection from interrupting the process.

screen -S ojs-migration
# then run the migration command
# detach with Ctrl+A, D

Step 7 — Migrate Uploaded Files

# Copy OJS 2 public files to OJS 3 public directory
cp -r /var/www/html/ojs/public/. /var/www/html/ojs3/public/

# Files directory is already specified in config.inc.php
# Verify the migration script copied files correctly
ls /var/www/ojs3-files/

Step 8 — Run the Upgrade Script

After the import, run the upgrade to apply any post-import schema migrations:

cd /var/www/html/ojs3
php tools/upgrade.php upgrade

Step 9 — Clear Caches

php lib/pkp/tools/cacheClear.php

Or via Administration → Clear Caches in the web interface.

Step 10 — Verify and Switch DNS/Webserver

Check that all journals, submissions, and users appear correctly
Verify galley files are accessible
Check article DOIs still resolve correctly
Update your webserver configuration to serve OJS 3 at the main domain
Keep OJS 2 available at a temporary URL for comparison during the verification period

Post-Migration Verification Checklist

All journals appear under Hosted Journals
User accounts and roles are intact
Submissions appear in correct stages
Published articles are accessible with their original URLs
Galley files (PDF, HTML) download correctly
DOIs resolve to the correct article pages
Email sending works (test from Settings → Website → Emails)
Reviewer and author notifications function correctly

Common Issues

Issue	Cause	Solution
Migration script exits with "DB Error"	Character encoding mismatch	Ensure both databases use `utf8mb4`
Missing galley files after migration	Wrong `files_dir` path in config	Verify the path in `config.inc.php` and re-run migration
Blank pages after switch	PHP version too old	Confirm server runs PHP 8.1+
Plugin errors on dashboard	OJS 2 plugins are incompatible	Disable all plugins; install OJS 3 equivalents
"Table doesn't exist" errors	Upgrade script not completed	Re-run `php tools/upgrade.php upgrade`
Custom theme broken	OJS 2 themes are not compatible	Switch to Default or Health Sciences theme; rebuild custom theme
URLs changed for articles	New URL pattern in OJS 3	Enable URL redirects from OJS 2 paths using your web server

Plugin Compatibility After OJS 2 → OJS 3 Migration

All OJS 2 plugins are incompatible with OJS 3. After migration you must:

Disable all plugins under Website → Plugins
Find OJS 3-compatible equivalents from PKP Plugin Gallery
Install and configure each replacement plugin individually

See the Plugin Upgrade Guide for a full compatibility matrix.

Rollback Procedure

If the migration fails or produces incorrect results:

# Stop serving OJS 3
# Restore the OJS 2 webserver configuration

# Drop the partial OJS 3 database
mysql -u root -p -e "DROP DATABASE ojs3; CREATE DATABASE ojs3 CHARACTER SET utf8mb4;"

# Remove the OJS 3 files directory
rm -rf /var/www/ojs3-files/*

# Restart from Step 4

Your OJS 2 installation and its database were never touched — restore the web server config to point to OJS 2 and you are back online immediately.

Next Steps

After a successful migration to OJS 3.3, continue upgrading:

➡️ OJS 3.3.x.x → OJS 3.4.y.y Migration Guide

What Changes in OJS 3​

Pre-Migration Checklist​

Migration Steps​

Step 1 — Upgrade to the Latest OJS 2.4.x First​

Step 2 — Install OJS 3.3 on a Separate Directory​

Step 3 — Create a New Database for OJS 3​

Step 4 — Configure OJS 3​

Step 5 — Run the OJS 3 Installer (Fresh Install)​

Step 6 — Import OJS 2 Data into OJS 3​

Step 7 — Migrate Uploaded Files​

Step 8 — Run the Upgrade Script​

Step 9 — Clear Caches​

Step 10 — Verify and Switch DNS/Webserver​

Post-Migration Verification Checklist​

Common Issues​

Plugin Compatibility After OJS 2 → OJS 3 Migration​

Rollback Procedure​

Next Steps​

Further Reading​