On this page
This guide follows the official nopCommerce procedure for upgrading to 4.90 or 5.00 and adds the parts that usually decide whether an upgrade goes smoothly: choosing the right version path and target, getting plugins and the theme ready, and testing the store before customers see it. For everything that is new in 5.00, read nopCommerce 5.0: release date, new features and what changes. Moving to nopCommerce from another platform instead? Read our nopCommerce migration guide.
How a nopCommerce upgrade works
nopCommerce does not upgrade itself. An upgrade replaces the application files with the new release, keeps your configuration, and brings the database schema up to date. You do it manually, ideally on a staging copy first.
The database step changed in version 4.40. Older releases shipped SQL upgrade scripts that you ran by hand, one version at a time. From 4.40 onwards, nopCommerce upgrades the database itself through migrations the first time the new release starts. The 4.90 source includes migrations for every release from 4.40 to 4.90, and the 5.00 source adds the 5.00 migrations on top, so a store on 4.40 or later can move to 4.90 or 5.00 in one step.
The application side is where most of the work sits. Each release targets a specific .NET runtime, and every plugin declares which nopCommerce versions it supports. A plugin built for 4.70 will not load on 4.90, and a plugin built for 4.90 will not load on 5.00, even if its code would still compile.
Find your nopCommerce upgrade path
Start from the version you run today. The table shows each release’s .NET runtime and how its database is upgraded.
| Version | .NET runtime | Database upgrade |
|---|---|---|
| 3.90 | .NET Framework 4.5.1 | SQL scripts (install 4.00 over the database, then run the 3.90 → 4.00 script) |
| 4.00 | .NET Framework 4.6.1 | SQL scripts, one version at a time |
| 4.10 – 4.20 | .NET Core 2.1 – 2.2 | SQL scripts, one version at a time |
| 4.30 | .NET Core 3.1 | SQL scripts to reach 4.30 |
| 4.40 | .NET 5 | Automatic migrations on first start |
| 4.50 | .NET 6 | Automatic migrations; check the connection string |
| 4.60 | .NET 7 | Automatic migrations on first start |
| 4.70 | .NET 8 | Automatic migrations on first start |
| 4.80 | .NET 9 | Automatic migrations on first start |
| 4.90 | .NET 9 | Automatic migrations; previous release line, patched to 4.90.8 |
| 5.00 | .NET 10 | Automatic migrations from 4.40 or later; latest release, 27 October 2026 |
In practice there are three paths:
- 4.40 or later → 4.90 or 5.00: deploy the target release over your settings; the migrations run on first start.
- 4.00 – 4.30 → 4.90 or 5.00: apply each SQL upgrade script in order until the database is at 4.30, then deploy the target release.
- 3.90 → 4.90 or 5.00: install 4.00 over the existing database and run the 3.90 → 4.00 script, continue with the scripts to 4.30, then deploy the target release.
Within the 4.90 line, patch releases (4.90.1, 4.90.2 and so on) are compatible with each other, so plugins and themes built for 4.90 keep working across them. The last 4.90 patch is 4.90.8. nopCommerce 5.00.0 was released on 27 October 2026, and 5.00 patches will work the same way. Always download releases from the official download page (opens in a new tab) or the nopCommerce GitHub releases (opens in a new tab).
Should you upgrade to 4.90 or 5.00?
nopCommerce 5.00 moves to .NET 10 and changes more than a usual release: forums, news and polls become plugins, the Manual payment method no longer ships, and every plugin needs a new build. The stable 5.00.0 release shipped on 27 October 2026, and the first bug-fix milestone for 5.00.x is dated 18 November 2026.
- Live store on 4.80 or older that needs to upgrade now: move to 5.00 if every plugin and the theme have 5.00 builds; otherwise move to 4.90.8. The plugin, theme and testing work carries over.
- Live store already on 4.90: rehearse the 5.00 upgrade on staging now, and go live once your plugins have 5.00 builds. Many stores wait for the first 5.00.x patch.
- New store, rebuild or long project: start on 5.00.
If you tested on the beta, switch to the stable release. Fifty of the 195 issues in the 5.00 milestone, many of them security fixes, were closed after the beta was published.
Before you start: inventory the store
Most failed upgrades are surprises that a short inventory would have found. Record these before touching anything:
- Current nopCommerce version (shown in the admin area and the system information page)
- Every installed plugin: system name, version, vendor and whether a build exists for your target version
- The active theme and how many default views it overrides
- Any edits made directly to nopCommerce core files or default views
- Hosting: Windows/IIS or Linux, the installed .NET runtime and the database server version
- Integrations and scheduled tasks that talk to an ERP, CRM, PIM, payment or shipping provider
- Where product pictures are stored: in the database or on the file system
- For 5.00: whether the store uses forums, news, polls or the Manual payment method, and which email templates were customised
The plugin list decides the timeline. If a plugin your checkout or ERP connection depends on has no build for your target version, that has to be solved before an upgrade date is realistic. The free StorePulse plugin lists the installed plugins that do not support the version you plan to move to. For 5.00 it also lists what else in the store needs work first, such as forums and news, the Manual payment method, old email template tokens and plugin code that uses changed APIs. Check plugin compatibility first: that guide explains what each result means and what to do about it.
How to upgrade nopCommerce step by step
The steps below follow the official upgrade documentation (opens in a new tab). Run them on a staging copy of the production database first, then repeat them on production.
1. Back up everything
Take a full backup of the database and every site file. This is the only reliable way back if something fails. If product pictures are stored on the file system, back up wwwroot\Images\ as well.
2. Upgrade the database scripts (4.30 and earlier only)
Skip this step if the store runs 4.40 or later. Otherwise, download the upgrade scripts and run them over the database one version at a time, reading the Readme.txt supplied with each script first.
3. Remove the old files but keep your settings
Delete the files of the previous version except the JSON files in App_Data, such as appsettings.json and plugins.json. Older installations may instead have dataSettings.json, Settings.txt or InstalledPlugins.txt; keep those too.
4. Install the runtime and upload the new release
Make sure the server has the runtime the target needs: .NET 9 for 4.90 or .NET 10 for 5.00. On IIS that means the ASP.NET Core Hosting Bundle for that version. Upload the new release files, or deploy your own build if you maintain the store from source. Our guide to .NET 10 hosting requirements covers IIS, Linux and Docker.
5. Update the settings files for the new version
Check that appsettings.json and plugins.json follow the format of the new release and still point to the production database. When you upgrade to 5.00, the first start also updates the data settings in appsettings.json itself, so keep a copy of the file from before the upgrade.
6. Start the store and let the migrations run
On first start, 4.40 and later releases apply the pending database migrations. Large catalogs can make this first start slow; let it finish and check the log for errors before doing anything else. If pictures are on the file system, copy wwwroot\Images\ back now.
7. Install the plugins and theme for the target, then test
Deploy the 4.90 or 5.00 builds of your plugins and theme, confirm in the admin plugin list that each one loads, then work through the test plan below before switching production traffic. On 5.00, also install the forums, news or polls plugin if the store uses them.
Keeping plugins and themes working after the upgrade
Each plugin has a plugin.json descriptor that lists the nopCommerce versions it supports. When the running version is not on that list, nopCommerce marks the plugin as not compatible with the current version and does not load it. It also rejects a plugin whose main assembly is missing, or one that collides with a different version of a library that is already loaded.
plugin.json · excerpt from an official 4.90 plugin
{
"SystemName": "Payments.CheckMoneyOrder",
"Version": "4.90.1",
"SupportedVersions": [ "4.90" ],
"FileName": "Nop.Plugin.Payments.CheckMoneyOrder.dll"
} Changing SupportedVersions by hand is not an upgrade. The plugin must also be built for the target runtime (.NET 9 for 4.90, .NET 10 for 5.00) against that release’s libraries, and any APIs that changed between releases have to be fixed. 5.00 changes more than usual, including Mapster in place of AutoMapper; see the 5.00 breaking changes for plugin developers. Some plugins ship their own database migrations as well, which run when the plugin is installed or updated.
| Situation | What to do |
|---|---|
| Third-party plugin with a build for the target | Download the vendor’s 4.90 or 5.00 build and read its upgrade notes before deploying. |
| Third-party plugin with no build for the target | Ask the vendor for a timeline, replace it, or plan a custom equivalent before committing to a date. |
| Custom plugin you own the source for | Retarget it to .NET 9 (4.90) or .NET 10 (5.00), update SupportedVersions, rebuild against the target source and fix API changes. |
| Custom theme | Compare overridden views with the new DefaultClean views and carry over upstream changes. |
| Edits inside core files | Re-apply them on the new source, or better, move them into a plugin so the next upgrade is cleaner. |
If you have custom plugins to port, or a theme that overrides many views, our nopCommerce plugin development team can rebuild them for 4.90 or 5.00.
What to test before go-live
Test on staging with a recent copy of production data, so real products, prices and customer roles are exercised:
- The store starts and the database upgrade completes without errors in the log
- Every required plugin shows as installed and compatible in the admin plugin list
- Home, category, product and search pages render correctly with the theme
- Product, category and manufacturer URLs are unchanged, and any old redirects still work
- Customer registration, sign-in and password reset
- Cart, discounts, tax and shipping rates on representative orders
- Checkout with every payment method, including refunds where supported
- Order, shipment and customer emails
- Scheduled tasks and integrations: imports, exports and ERP or CRM synchronisation
- Admin workflows the team uses daily, including any custom admin screens
- Page speed on the slowest category and search pages compared with the old version
- For 5.00: product attribute pictures, forum, news and poll content, customised order emails and product rich results
Adapt the list to your store. A B2B store should add customer-specific prices, approvals and quick order; a marketplace should add vendor flows.
Plan the rollback before you need it
If something goes wrong, the official advice is to restore your backup and put back the files from the previous version. That only works cleanly if you have a backup taken immediately before the upgrade and a short freeze on orders and catalog edits during the cut-over.
Extra steps when upgrading to nopCommerce 5.00
The procedure above applies to 5.00. Add these checks, which come from changes in the 5.00 release:
| When | What to do |
|---|---|
| Before | Confirm your host offers .NET 10. A server with only the .NET 9 runtime cannot start 5.00. |
| Before | Replace the Manual payment method if the store uses it; Payments.Manual no longer ships with nopCommerce. |
| Before | Get 5.00 builds of every plugin and the theme. Plugins that use AutoMapper or the removed payment redirect helper need code changes. |
| Before | List email templates that use %Order.CustomValues%; 5.00 splits it into several tokens. |
| After | Install the Misc.Forums, Misc.News or Misc.Polls plugin if the store uses forums, news or polls, and check the content. |
| After | Check product attribute value and combination pictures, which 5.00 moves to multiple pictures. |
| After | Check product rich results; products with variants now use the ProductGroup schema type. |
If you tested on the beta, repeat the upgrade from a fresh copy of the 4.90 database with the stable release. The beta’s upgrade could lose attribute value and combination pictures; that was fixed afterwards. Stores with old picture links left by 4.70 can still get duplicate attribute pictures after 5.0, so check for them on 4.90. For the full list of 5.00 changes, see nopCommerce 5.0: release date, new features and what changes.
Frequently asked questions
Can I upgrade nopCommerce directly from 4.40 to 4.90 or 5.0?
For the database, yes. Both 4.90 and 5.00 ship the migrations for every release from 4.40 onwards and apply them on first start, so you do not need to install each intermediate release. Every plugin and the theme still need versions built for the target before you go live.
Should I upgrade to 4.90 or straight to 5.0?
Go to 5.00 when every plugin and your theme have 5.00 builds; the stable release shipped on 27 October 2026. If a plugin you depend on has no 5.00 build yet, upgrade a live store to 4.90.8 now and move to 5.00 later. New stores and rebuilds should start on 5.00.
What changes in the upgrade procedure for nopCommerce 5.0?
The steps are the same. The server needs .NET 10 instead of .NET 9, the first start updates appsettings.json itself, and stores that use forums, news or polls install the new plugins for them afterwards. The Manual payment method no longer ships, so replace it before upgrading.
How do I upgrade from nopCommerce 4.30 or earlier?
Apply the official SQL upgrade scripts one version at a time until the database reaches 4.30, reading each script’s Readme.txt first. Then deploy the target release (4.90 or 5.00), which upgrades the database from 4.30 onwards through migrations. Stores on 3.90 install 4.00 over the existing database and run the 3.90 to 4.00 script first.
Does nopCommerce upgrade automatically?
No. nopCommerce has no automatic or one-click upgrade. You replace the application files manually and keep your settings files. Since 4.40, only the database step runs automatically, when the new release starts for the first time.
Why does a plugin disappear after the upgrade?
nopCommerce marks a plugin as incompatible and does not load it when the plugin does not declare support for the running version, when its main assembly is missing, or when it conflicts with a different version of an already loaded library. Install a build made for the target version.
Will the upgrade change my store’s URLs?
A standard upgrade keeps the search engine names of products, categories and manufacturers. URLs can change when a store depends on custom routing or an SEO plugin that has no compatible version, so compare URLs on staging before go-live.
How long does a nopCommerce upgrade take?
It depends far more on plugins, theme overrides and core changes than on the database. A store with only official plugins and the default theme is a small job; a store several versions behind with custom plugins and core edits needs an assessment before anyone can give an honest estimate.
Plan your nopCommerce upgrade
Start with the inventory, choose 4.90 or 5.00, confirm a build for that version exists for every plugin you depend on, and rehearse the full upgrade on staging before you pick a go-live date.
If you would rather hand it over, our nopCommerce migration and upgrade services cover the assessment, plugin and theme porting, staging rehearsal and go-live. Send your current version and plugin list to contact@cartenvo.com and we will outline the path.
Moving catalog data between stores as part of the upgrade? Read our nopCommerce product import and export guide. If the store is slow after the upgrade, see our nopCommerce performance optimization service.