skip to content

With the Angular CLI, when do you run `ng update <package> --migrate-only --from <version>`, and how does it differ from a normal `ng update`?

level: middleimportance: should knowfreq 32%

answer

  1. versions already bumped elsewhere
  2. no install, migrations only
  3. --to defaults to the installed version
  4. --name runs one migration
  5. one package at a time

basics

~20 s

Use it when versions were bumped outside ng update (a package manager, a bot, a shared catalog), so migrations never ran. It installs nothing and runs migrations above --from up to --to, which defaults to the installed version.

solid answer

~50 s

A normal `ng update` resolves new versions, installs them and then runs migrations for the range between old and new. `--migrate-only` skips resolving and installing: it takes the package as it is installed now and runs its migrations. `--from` says where the code actually is, and `--to` says how far to go, defaulting to the installed version; `--to` requires `--from`. It is for when versions were changed without `ng update`: a dependency bot's pull request, a manual install, a failed update you finished by hand, or pnpm/yarn catalogs, which the CLI cannot edit and for which it prints the exact `--migrate-only --from` commands to run. `--name <migration>` instead runs one migration by name, such as an optional one you skipped. These options work only with a single package, and `--name` cannot be combined with `--from`/`--to`.

code

bash · 6 lines
bash
# versions were bumped by a bot from 21.2.3 to 22.2.0
ng update @angular/core --migrate-only --from 21.2.3
ng update @angular/cli  --migrate-only --from 21.2.3

# run a single, previously skipped optional migration
ng update @angular/cli --name use-application-builder

go deeper

for a junior

Know that migrations only run through ng update, and that --migrate-only exists to run them later.

for a middle

Use --migrate-only with --from and --to, and --name for a single migration, and know the single-package restriction.

for a senior

Recover repositories where versions moved without migrations (bots, catalogs, interrupted updates) and choose the correct from-version from history.

for a principal

Set up dependency automation so Angular majors go through ng update, or through a documented migrate-only step, rather than silent version bumps.

## Why migrations can go missing Migrations run as part of `ng update` after the install, for the version range between what was installed and what was just installed. Any other way of changing versions skips that step: - a dependency bot or a teammate bumps `@angular/core` in `package.json` and runs an install; - a monorepo defines versions in a **pnpm or yarn catalog**, which `ng update` refuses to edit; - an `ng update` was interrupted after the install, or someone reverted the migrated code by mistake. The versions are now new while the code is still old. `--migrate-only` exists to catch up. ## What the options do | Option | Meaning | |---|---| | `--migrate-only` | Do not resolve or install versions; only run migrations for the named package | | `--from <version>` | The version the code was last migrated for; migrations above it run. Implies `--migrate-only` | | `--to <version>` | The upper bound; requires `--from`. Defaults to the installed version | | `--name <migration>` | Run a single migration by name. Implies `--migrate-only`; cannot be combined with `--from`/`--to` | All of them are only available when **one package** is named. A version specifier on the package (`@angular/core@22`) has no effect in this mode, and the CLI warns about it. The selection rule is the same as for a normal update: a migration runs when its `version` is greater than `--from` and no greater than `--to`. Required migrations run in version order, and optional ones are offered in a prompt. ## Typical uses 1. **After a bot bump.** The pull request moved `@angular/core` from 21.2.3 to 22.2.0 without migrations: ```bash ng update @angular/core --migrate-only --from 21.2.3 ``` 2. **Catalog-managed monorepos.** When target versions come from a catalog, `ng update` stops, lists the packages and prints the steps: update the catalog file by hand, run the install, then run `ng update <pkg> --migrate-only --from <current>` for each package. 3. **A skipped optional migration.** Optional migrations are listed during the update, and in a non-interactive terminal each is printed with `ng update <pkg> --name <migration>`, for example: ```bash ng update @angular/cli --name use-application-builder ``` 4. **Replaying a range.** `--from 21.0.0 --to 21.2.0` re-runs only that slice, for example after rebasing a long-lived branch onto a migrated main. ## How it differs from a normal update - **No version resolution or install.** The peer dependency check and the one-major rule, both parts of version resolution, are not involved. You are responsible for the versions already being right. - **One package at a time.** A normal update can name several packages and follows package groups. Here you run it per package: `@angular/core` for framework migrations, `@angular/cli` for workspace migrations, and each library separately. - **Same safety rules.** The clean-tree check and `--create-commits` apply as usual. ## Checking what ran The log has the same shape as a normal update. `** Executing migrations of package '@angular/core' **` starts the package. Each migration prints its title and description, then `Migration completed (N files modified).` or `No changes made`. Optional migrations are listed separately with a prompt. Two habits make the run auditable: 1. Add `--create-commits`, so each migration that changed files becomes its own commit named after it. 2. Build and run the tests straight after, exactly as after a normal update, because the code is only now catching up with the installed versions. If a migration fails, the run stops with `Migration failed. See above for further details.` Migrations work on the schematics virtual tree, so the failed one leaves no half-written files. Fix the cause and re-run. Migrations earlier in the range run again, which is usually harmless because most are written to be idempotent, and per-migration commits show exactly what changed the second time. ## Pitfalls - **Wrong `--from`.** Too low re-runs migrations that already ran; most are written to be idempotent, but not all are harmless. Too high skips needed ones. Take the value from git history of `package.json` or the lockfile. - **Forgetting the CLI package.** Bumping `@angular/cli` outside `ng update` also skips `@schematics/angular` workspace migrations, which `ng update @angular/cli --migrate-only --from ...` runs. - **Using it to jump majors.** It runs migrations, but it does not make an install across several majors supported.

  • Why can't you combine `--name` with `--from`?
    They select migrations in different ways. `--name` picks one migration explicitly, whatever its version. `--from`/`--to` select every migration in a version range. The CLI declares them as conflicting options, so you choose either a named migration or a range.
  • How do you find the right `--from` value after a bot bump?
    Look at the version before the bump: the previous `package.json` or lockfile entry in git history, or the bot's pull request title. Use the version the code was last migrated for. Everything above it, up to the installed version, then runs.

  • Thinks --migrate-only also installs the requested version
  • Passes several packages to --migrate-only in one command
  • Believes bumping versions with a package manager runs Angular migrations
  • Combines --name with --from and expects both to apply
  • Guesses --from instead of taking it from git history