On this page
This guide follows the official nopCommerce procedure and adds the parts that usually decide whether an upgrade goes smoothly: choosing the right version path, getting plugins and the theme ready, and testing the store before customers see it. 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, so a store on 4.40 or later can move to 4.90 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, 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 | Current stable release line |
In practice there are three paths:
- 4.40 or later → 4.90: deploy 4.90 over your settings; the migrations run on first start.
- 4.00 – 4.30 → 4.90: apply each SQL upgrade script in order until the database is at 4.30, then deploy 4.90.
- 3.90 → 4.90: install 4.00 over the existing database and run the 3.90 → 4.00 script, continue with the scripts to 4.30, then deploy 4.90.
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. At the time of writing the latest patch is 4.90.8. Always download releases from the official download page (opens in a new tab) or the nopCommerce GitHub releases (opens in a new tab).
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 4.90 build exists
- 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
The plugin list decides the timeline. If a plugin your checkout or ERP connection depends on has no 4.90 build, that has to be solved before an upgrade date is realistic.
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; on IIS that means the ASP.NET Core Hosting Bundle. Upload the new release files, or deploy your own build if you maintain the store from source.
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.
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 4.90 plugins and theme, then test
Deploy the 4.90 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.
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 .NET 9 against the 4.90 libraries, and any APIs that changed between releases have to be fixed. 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 4.90 build | Download the vendor’s 4.90 build and read its upgrade notes before deploying. |
| Third-party plugin with no 4.90 build | 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, update SupportedVersions, rebuild against the 4.90 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.
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
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.
What about nopCommerce 5.00?
nopCommerce 5.00 is available as a beta at the time of writing and targets .NET 10. Beta releases are for testing plugins and themes, not for production stores. For a live store, upgrade to the latest stable 4.90 release now; the plugin, theme and testing work you do for 4.90 also makes the later move to 5.00 smaller.
Frequently asked questions
Can I upgrade nopCommerce directly from 4.40 to 4.90?
For the database, yes. nopCommerce 4.90 ships the migrations for every release from 4.40 onwards and applies them on first start, so you do not need to install each intermediate release. Every plugin and the theme still need 4.90-compatible versions before you go live.
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, 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, confirm a 4.90 build 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.