This is mainly a practical reference. Before following any of these steps, compare them against your own project setup and dependency stack.
Start with Angular’s official update guide
Angular provides a dedicated update guide that helps you check what needs attention before and after upgrading, based on the versions and features your project uses. It is worth reviewing that first, especially if your app has custom build settings or several UI libraries layered on top of Angular.
Using npm-check-updates to bump dependencies
npm-check-updates is a convenient npm tool that updates the dependencies listed in package.json to newer versions in one pass.
Install it globally with:
npm install -g npm-check-updates
Then check and update version ranges in the project:
ncu -u
One example upgrade result looked like this:
PS C:\Users\44684\Desktop\FlowersInkV2> ncu -u
Upgrading C:\Users\44684\Desktop\FlowersInkV2\package.json
[====================] 35/35 100%
@angular-devkit/build-angular ^17.3.6 → ^20.0.5
@angular/animations ^17.3.0 → ^20.0.6
@angular/cli ^17.3.6 → ^20.0.5
@angular/common ^17.3.0 → ^20.0.6
@angular/compiler ^17.3.0 → ^20.0.6
@angular/compiler-cli ^17.3.0 → ^20.0.6
@angular/core ^17.3.0 → ^20.0.6
@angular/forms ^17.3.0 → ^20.0.6
@angular/platform-browser ^17.3.0 → ^20.0.6
@angular/platform-browser-dynamic ^17.3.0 → ^20.0.6
less-loader ^12.2.0 → ^12.3.0
mermaid ^10.9.1 → ^11.7.0
ng-zorro-antd ^17.4.1 → ^20.0.0
ngx-markdown ^17.0.0 → ^20.0.0
prismjs ^1.29.0 → ^1.30.0
rxjs ~7.8.0 → ~7.8.2
tslib ^2.3.0 → ^2.8.1
typescript ~5.4.2 → ~5.8.3
zone.js ~0.14.3 → ~0.15.1
Run npm install to install new versions.
After that, the normal next step is npm install. If everything goes smoothly, the upgrade is essentially done once installation finishes.
In practice, though, I repeatedly ran into the same installation failure when upgrading Angular projects, and it was tied to @angular-devkit/build-angular. The notes below are the workaround that worked for me.
The npm install failure
This was the error:
PS C:\Users\44684\Desktop\FlowersInkV2> npm install
npm error code ERESOLVE
npm error ERESOLVE could not resolve
npm error
npm error While resolving: [email protected]
npm error Found: @angular-devkit/[email protected]
npm error dev @angular-devkit/build-angular@"^20.0.5" from the root project
npm error
npm error Could not resolve dependency:
npm error dev @angular-devkit/build-angular@"^20.0.5" from the root project
npm error
npm error Conflicting peer dependency: @angular/[email protected]
npm error node_modules/@angular/compiler-cli
npm error peer @angular/compiler-cli@"^20.0.0" from @angular-devkit/[email protected]
npm error node_modules/@angular-devkit/build-angular
npm error dev @angular-devkit/build-angular@"^20.0.5" from the root project
npm error
npm error Fix the upstream dependency conflict, or retry
npm error this command with --force or --legacy-peer-deps
npm error to accept an incorrect (and potentially broken) dependency resolution.
npm error
npm error
npm error For a full report see:
npm error C:\Users\44684\AppData\Local\npm-cache\_logs\2025-07-03T08_57_19_511Z-eresolve-report.txt
npm error A complete log of this run can be found in: C:\Users\44684\AppData\Local\npm-cache\_logs\2025-07-03T08_57_19_511Z-debug-0.log
I cannot say with certainty that I know the exact root cause, but my understanding is that @angular/compiler-cli and @angular-devkit/build-angular were not updating in sync, which caused the dependency conflict.
The process below allowed the upgrade to complete successfully, but it should still be treated as a reference rather than a universal fix.
Before doing anything else, make a full backup of the project if possible.
1. Clean out the dependency environment
Delete the node_modules folder and the package-lock.json file manually.
If your editor is slow at deleting large directories, it is often faster to open the folder in Windows File Explorer and remove them there.
2. Force-install dependencies
This is the step that deserves the most caution.
If your project depends on a large number of frameworks or UI libraries, make sure your backup is complete before proceeding.
I once used this approach on an Angular 11 project that combined Fuse, Ng-Zorro, Angular Material, and DevUI. After forcing dependency installation, the project was no longer usable at all. The only recovery path was to delete it, pull the code again, and reinstall everything from scratch.
Run:
npm install --legacy-peer-deps --force
--legacy-peer-deps ignores peer dependency conflicts, and --force pushes past version mismatch issues. That may get the install through, but it does not guarantee the application will still run correctly afterward.
3. Upgrade the global Angular CLI
Run:
npm install -g @angular/[email protected]
This updates the global Angular CLI to the target major version.
4. Run Angular migrations
Next, execute:
ng update @angular/core @angular/cli --allow-dirty --force
This step is important because Angular migrations can automatically adjust project configuration and patch compatibility issues in the codebase.
However, this is where another error appeared:
PS C:\Users\44684\Desktop\FlowersInkV2> ng update @angular/core @angular/cli --allow-dirty --force
Node.js version v22.10.0 detected.
The Angular CLI requires a minimum Node.js version of v20.19 or v22.12.
Please update your Node.js version or visit https://nodejs.org/ for additional instructions.
The fix was straightforward: the local Node.js version was v22.10.0, which was too low for this Angular CLI release. Updating Node.js to v22.12.0 solved the problem. Based on the error message, v20.19.0 would also satisfy the requirement.
5. Verify that the project still runs
Finally, start the project with:
ng serve
If it runs successfully, the upgrade is complete.