Skip to main content
OJS for Everyone Logo
OJS for EveryoneThe Practical GuidebookRSYN Research LLP

OJS Upgrades

Everything you need to know about upgrading your OJS installation — from why upgrades matter to the step-by-step process and the OJS 2.x to 3.x migration path.

Why do I need to upgrade my OJS?​

Upgrades are necessary for three key reasons:

  1. Security — Each release patches known vulnerabilities. Outdated OJS is an easy target for automated bots exploiting published CVEs. See the Security FAQ for full details.
  2. Bug fixes — Workflow bugs, export failures, and display issues are resolved in each release.
  3. New features — Each minor version adds new capabilities, improved statistics, better indexing support, and editorial workflow enhancements.
  4. Compatibility — OJS upgrades maintain compatibility with current PHP, MySQL, and PostgreSQL versions. Running old OJS on a newly updated server causes errors.

How do I order an OJS upgrade from a managed hosting provider?​

If you use a managed OJS hosting provider:

  1. Contact your host's support team via email or ticket.
  2. Request an OJS upgrade and specify the current version and the target version.
  3. Confirm a maintenance window — most hosts schedule upgrades during off-peak hours.
  4. The host performs the upgrade on your behalf and notifies you on completion.
  5. Test your journal thoroughly after the upgrade: check article pages, settings, email, plugins, and statistics.

Managed hosts typically include scheduled upgrades in their service plan or charge a modest upgrade fee.

Can I perform the OJS upgrade myself?​

Yes, if you have server access and comfort with command-line tools. The process involves:

  1. Backup — database and files_dir before anything else.
  2. Download the new OJS release from pkp.sfu.ca.
  3. Replace the codebase — overwrite the OJS files, keeping config.inc.php, public/, and files_dir intact.
  4. Run the upgrade script:
php tools/upgrade.php upgrade
  1. Clear caches from the Administration panel.
  2. Test thoroughly.

Full instructions are in the PKP Technical Upgrade Guide.

warning

Never skip major or minor version series when upgrading. Upgrade step-by-step through each version series (e.g., 3.1 → 3.2 → 3.3 → 3.4 → 3.5). Skipping versions can cause data migration errors.

How does the upgrade process work?​

At a high level:

  1. New code is deployed over the existing installation.
  2. The upgrade script (php tools/upgrade.php upgrade) runs database migration scripts that update the database schema and migrate data to new structures.
  3. Template and data caches are cleared.
  4. The site operates on the new version.

The upgrade script is idempotent — if it fails halfway, you can restore the backup and try again. It does not permanently alter data until each migration step succeeds.

How long does an OJS upgrade take?​

For most journals:

  • Preparation and backup: 15–30 minutes.
  • Code replacement: 5–10 minutes.
  • Database upgrade script: 5–30 minutes depending on database size (journals with thousands of articles may take longer).
  • Testing: 15–30 minutes.

Total: 1–2 hours for a standard installation. Large multi-journal installations or databases with millions of records may take several hours.

Can upgrades be performed on any version of OJS?​

Yes, but you must upgrade in sequence through major versions:

  • OJS 2.4.x → OJS 3.x requires a migration path (see below).
  • Within OJS 3.x (e.g., 3.3 → 3.5): upgrade through intermediate minor versions as recommended in PKP release notes.

PKP provides upgrade scripts for all supported paths. Very old installations (OJS 1.x, OJS 2.0–2.3) may require a more complex migration — consult the PKP Community Forum.

What are the main differences between OJS 3.x and OJS 2.x?​

OJS 3 was a complete rewrite of OJS 2 with a modernised architecture and interface:

FeatureOJS 2.xOJS 3.x
InterfaceOlder, non-responsive designModern, mobile-responsive
WorkflowSeparate pages per stageUnified, tab-based submission view
RolesFixed system rolesFlexible, configurable roles
Review typesDouble-blind onlyDouble-blind, single-blind, open
Plugin systemOlder plugin APIRedesigned, more powerful plugin API
StatisticsBasic COUNTER 4COUNTER 5 + usage statistics dashboard
DOI managementSeparate CrossRef pluginUnified DOI plugin with multiple agencies
MultilingualLimitedFull multilingual per-submission support
REST APINoneFull REST API v1
File managementFlat file listStructured component-based file management
PHP/MySQL compatibilityPHP 5.xPHP 7.4+ / PHP 8.x

How do I upgrade from OJS 2.x to OJS 3.x?​

Migrating from OJS 2.x to 3.x is more complex than a standard minor-version upgrade:

  1. Back up everything — database and all files.
  2. Review PKP's upgrade documentation for your specific version path: Upgrading from OJS 2.4.8 to 3.x.
  3. Test the migration on a staging server before migrating your production site.
  4. Run the migration script — PKP provides a migration script that converts OJS 2 data structures to OJS 3 format.
  5. Review and correct data — some data (especially custom blocks, nav menu items, and theme settings) does not migrate automatically and must be reconfigured.
  6. Check plugins — most OJS 2 plugins are not compatible with OJS 3. Find equivalent OJS 3 plugins or alternatives.

Strongly recommended: Have an experienced OJS administrator or managed hosting provider perform the OJS 2 → 3 migration.

Can I move my OJS 2.x customizations to OJS 3.x?​

Theme customizations: OJS 2 themes are not compatible with OJS 3. You must choose an OJS 3 theme and redo any custom CSS for the new theme.

Plugin customizations: OJS 2 plugins use a different API and are not compatible with OJS 3. Look for equivalent plugins in the PKP Plugin Gallery or commission new development.

Editorial workflow customizations: Journal settings, email templates, and section configurations are migrated by the upgrade script, but review them carefully after migration — some settings reset to defaults.

Where can I find user guide and documentation for OJS 3.x?​

Will existing roles, login credentials, and permissions in OJS 2.x be ported to OJS 3.x?​

Yes, in most cases:

  • User accounts and passwords are migrated.
  • Journal Manager and Editor roles are migrated to equivalent OJS 3 roles.
  • Author and Reviewer roles are migrated.
  • Section Editor assignments are migrated.

However, role structures between OJS 2 and OJS 3 differ, so some role mappings may need adjustment after migration. Review all user accounts and role assignments after upgrading.

Will usage statistics in OJS 2.x be migrated to OJS 3.x?​

Legacy statistics (view/download counts from OJS 2) are migrated to OJS 3's statistics system, but the migration may not be perfect due to differences in how the two versions tracked statistics.

The PKP Community Forum has community-tested advice on statistics migration. In some cases, statistics data is best transferred manually or treated as a starting baseline rather than a precise historical record.

Further Reading​