OJS Upgrade Guide · Verified August 2026

How to Upgrade Open Journal Systems (OJS) Safely

A practical step-by-step guide to planning, testing, running, and verifying an OJS upgrade without treating your live journal as the test environment.

Start the upgrade checklistGet professional OJS upgrade help

Quick answer: how do you upgrade OJS?

To upgrade Open Journal Systems, first record the current OJS and server versions, choose a supported target release, test the complete upgrade on a protected staging copy, create verified database and file backups, prepare a clean target codebase, merge the configuration carefully, run the OJS preflight check, execute php tools/upgrade.php upgrade, and verify articles, files, users, editorial workflows, email, plugins, themes, DOI links, OAI-PMH, and backups before reopening the production journal.

Current PKP release checked: OJS 3.5.0-5 LTSOfficial source reviewed: 26 August 2026
On this page
  1. Current OJS releases
  2. Eight upgrade steps
  3. Backup checklist
  4. Upgrade commands
  5. Post-upgrade tests
  6. Failed upgrade recovery
  7. Search and DOI checks
  8. OJS upgrade FAQs

What an OJS upgrade changes

An OJS upgrade can change the application code, database structure, configuration options, email templates, scheduled tasks, user sessions, plugin APIs, theme templates, and server requirements. The public journal may look similar after a minor maintenance update, but the work underneath can still affect submissions, editorial decisions, article files, metadata exports, and integrations.

That is why a safe upgrade is a controlled migration of software and data—not simply replacing a few folders. PKP recommends testing the upgrade on a sandbox copy and keeping complete backups that can restore the earlier working state.

Which OJS version should you upgrade to in 2026?

Use PKP's official download page and release documentation when choosing a target. Do not select a version only because its number is higher; confirm its support status, system requirements, upgrade path, plugin compatibility, and suitability for your journal.

Official release snapshotPKP status on 26 August 2026Planning note
OJS 3.5.0-5LTS, released 30 June 2026Review the 3.5 requirements, release notebook, configuration changes, theme, and every required plugin before upgrading.
OJS 3.4.0-10Release published 21 November 2025Check whether remaining on 3.4 or moving to an LTS release best matches your support and compatibility needs.
OJS 3.3.0-22 LTSPKP lists support until at least 1 January 2027Plan the next supported upgrade rather than waiting until after end of support.
Older OJS installations may require intermediate upgrades. Read the docs/UPGRADE file included with the exact target package. Do not assume that every older version can jump directly to the newest release.

How to upgrade OJS step by step

Step 1

Record the current OJS and server environment

Sign in as Site Administrator and review Administration → System Information. Record the full OJS build number, PHP version, database engine and version, operating environment, active journals, installed languages, theme, enabled plugins, custom code, scheduled tasks, email method, files directory location, and disk usage.

This inventory is the baseline for compatibility decisions and post-upgrade testing. Save screenshots or an export of important settings instead of relying on memory.

Step 2

Choose the target release and confirm the upgrade path

Download OJS only from PKP's official release page. Read the target package's docs/README, docs/UPGRADE, release notes, and new config.TEMPLATE.inc.php. Check whether an intermediate release is required for your current version.

Review required plugins in the PKP Plugin Gallery or their official repositories. A plugin or custom theme that works on the current journal may not work on the target release.

Step 3

Create a protected staging copy

Copy the production database, OJS files directory, public directory, code, and configuration to a separate staging environment. Point staging to copied data—never to the live database or live private files. Prevent public indexing with authentication or a noindex response, and prevent staging from emailing real users.

Run the entire upgrade on staging first. Record its duration, warnings, errors, manual fixes, and the final validation result. Production should repeat an already-tested procedure.

Step 4

Create complete, synchronized, and verified backups

Take a fresh backup immediately before the production upgrade. A recoverable OJS backup normally includes:

  • Database export
  • Private files_dir contents
  • Public directory and uploaded images
  • Current application code
  • config.inc.php
  • Custom plugins, themes, and locale changes
  • Web server and scheduled-task notes
  • A tested restoration procedure

Keep the database and files from the same point in time. Verify that the backup files exist, have sensible sizes, can be read, and can be restored in staging.

Step 5

Prepare the target server and clean OJS codebase

Confirm the target package's PHP, database, extension, web server, and command-line requirements. Correct resource limits, file permissions, storage space, and paths before starting.

Prepare a clean directory from the official OJS package. Do not unpack the new release over the old application directory. Bring across the required public content and site-specific assets deliberately. Keep the private files directory outside the web-accessible application directory.

Step 6

Merge configuration and compatible extensions carefully

Do not blindly replace the new configuration template with an old file. Compare the previous config.inc.php with the target release's config.TEMPLATE.inc.php, preserve necessary database and path values, and account for new, renamed, or removed settings.

Install only target-compatible plugin and theme releases. Reapply custom code as reviewed changes rather than copying entire old core directories into the new package.

Step 7

Put production in maintenance mode and run the CLI upgrade

Notify the editorial team, stop new submissions and edits, take the final synchronized backup, and make the production site unavailable to normal users. From the target OJS application directory, run the preflight check with the command-line PHP version intended for the upgrade:

php tools/upgrade.php check

Resolve errors before continuing. When the staging procedure and preflight result are acceptable, run:

php tools/upgrade.php upgrade

Capture the complete command output. Do not close the terminal or interrupt a running database migration because the browser appears idle.

Step 8

Verify the upgraded journal before reopening it

A successful command is the beginning of validation, not the end. Test the administrator dashboard and each active journal. Compare record counts and inspect representative old and recent issues.

  • Homepage, archives, issue, and article pages
  • PDF and supplementary-file downloads
  • Administrator, editor, author, and reviewer login
  • Submission and editorial workflow
  • SMTP email and password reset
  • Theme, navigation, blocks, and languages
  • Plugins and scheduled tasks
  • Search, OAI-PMH, DOI, ORCID, and exports

Review PHP, web server, database, OJS, and scheduled-task logs. Create a new post-upgrade backup only after validation is complete.

What should you do if the OJS upgrade fails?

Do not experiment repeatedly on the only production copy. Save the error output and logs. If a database migration partially ran, restore the synchronized pre-upgrade database, files, code, and configuration before repeating a corrected procedure. Mixing a restored code directory with a partly upgraded database can make diagnosis and recovery harder.

Reproduce the failure in staging, identify the first meaningful error, and check the target release documentation and PKP Community Forum. Common causes include an unsupported upgrade path, wrong command-line PHP version, missing PHP extensions, database inconsistencies, mixed character sets or collations, incomplete configuration changes, insufficient time or memory limits, file permissions, incompatible plugins, and custom themes.

Search, Google Scholar, DOI, and metadata checks after upgrading OJS

An OJS upgrade can change templates, HTML metadata, plugin output, URLs, or access to article files. It does not automatically improve or destroy indexing, but unnoticed technical changes can affect discovery. After launch:

  • Confirm important article URLs still return HTTP 200 and canonical URLs remain correct.
  • Open article PDFs without an administrator login where the journal's access policy permits public full text.
  • Inspect citation metadata, Dublin Core output, OAI-PMH records, sitemap behavior, robots rules, and structured data.
  • Test DOI links and update registered destination URLs if article URLs changed.
  • Use permanent one-to-one redirects for important URLs that could not be preserved.
  • Check Google Search Console and server logs for new crawl errors after deployment.

OJS upgrade frequently asked questions

Can I upgrade OJS directly to the newest version?

Not always. The supported path depends on the current and target releases. Check the docs/UPGRADE file included with the exact target package and use intermediate versions when PKP requires them.

Can I upgrade OJS from the browser?

OJS may expose a web upgrade route, but command-line execution is generally easier to monitor and less vulnerable to browser or web-server timeouts. Use the procedure documented for the target release and test it in staging.

What is the OJS upgrade command?

The commonly documented CLI command is php tools/upgrade.php upgrade, run from the OJS application directory. Run php tools/upgrade.php check first and ensure the CLI uses the intended PHP version.

How long does an OJS upgrade take?

There is no reliable universal duration. It depends on source and target versions, database and file size, number of journals, server performance, plugin and theme work, errors, and validation. A staging rehearsal gives the best estimate for the production window.

Will articles, users, and submissions remain after an upgrade?

A successful supported upgrade is designed to migrate the existing data, but a safe plan still requires complete backups, staging verification, compatible extensions, and post-upgrade record checks.

Does an OJS upgrade guarantee Google Scholar indexing?

No. OJS, GetOJS, and hosting providers cannot guarantee inclusion in Google Scholar or another independent index. The upgrade should preserve accessible article pages, stable URLs, correct scholarly metadata, and public files where required.

When should I hire an OJS upgrade specialist?

Professional help is useful for unsupported or very old versions, multi-journal installations, large archives, custom themes or plugins, previous failed upgrades, limited server access, strict downtime requirements, or teams without tested database restoration experience.

Official sources used for this guide

Release information was checked against PKP on 26 August 2026. Always recheck the official download page before starting a future upgrade.

Need GetOJS to plan and run the upgrade?

Share your journal URL, current OJS version, target version, hosting environment, journal count, archive size, active plugins, theme customizations, and any earlier upgrade error. GetOJS can scope staging, backup, compatibility, production, and validation work.

View OJS Upgrade Services