> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nrwl/nx/llms.txt
> Use this file to discover all available pages before exploring further.

# nx migrate

> Update Nx and its plugins, then apply the generated code migrations.

```bash theme={null}
nx migrate [packageAndVersion] [options]
```

`nx migrate` is a two-step process:

1. **Update packages** — resolves the new versions of Nx packages and their plugins, updates `package.json`, and generates a `migrations.json` file listing the code transformations to apply.
2. **Apply migrations** — runs the transformations listed in `migrations.json` against your source files.

<Note>
  Run `npm install` (or your package manager's install command) after step 1 and before step 2 to install the updated packages.
</Note>

## Migration workflow

<Steps>
  <Step title="Generate migrations.json">
    Target the version you want to migrate to. Using `latest` resolves the latest stable release:

    ```bash theme={null}
    nx migrate latest
    # or target a specific version
    nx migrate @nx/workspace@20.0.0
    # or update a specific plugin
    nx migrate @nx/react@latest
    ```

    This updates `package.json` and creates `migrations.json`.
  </Step>

  <Step title="Install updated packages">
    ```bash theme={null}
    npm install
    ```
  </Step>

  <Step title="Apply the migrations">
    ```bash theme={null}
    nx migrate --run-migrations
    ```

    This runs every migration listed in `migrations.json` against your workspace files.
  </Step>

  <Step title="Review and commit the changes">
    Inspect the file changes produced by the migrations, run your tests, and commit the result.
  </Step>
</Steps>

## Arguments

<ParamField path="packageAndVersion" type="string">
  The target package and version to migrate to (e.g., `@nx/workspace@20.0.0`, `latest`, `@nx/react@latest`).
</ParamField>

## Options

<ParamField query="--run-migrations" type="string">
  Execute code migrations from a file. When no file path is provided, reads from `migrations.json` in the current directory.

  ```bash theme={null}
  nx migrate --run-migrations
  nx migrate --run-migrations=custom-migrations.json
  ```
</ParamField>

<ParamField query="--if-exists" type="boolean" default="false">
  When using `--run-migrations`, continue successfully even if the migrations file does not exist.
</ParamField>

<ParamField query="--from" type="string">
  Override the currently installed versions of packages when computing which migrations to run. Useful when the installed versions are not accurate. Accepts a comma-separated list.

  ```bash theme={null}
  nx migrate latest --from="@nx/react@18.0.0,@nx/js@18.0.0"
  ```
</ParamField>

<ParamField query="--to" type="string">
  Override the target versions that the migrator would otherwise calculate. Accepts a comma-separated list.

  ```bash theme={null}
  nx migrate @nx/workspace@20.0.0 --to="@nx/react@20.0.0,@nx/js@20.0.0"
  ```
</ParamField>

<ParamField query="--create-commits" type="boolean" default="false">
  Automatically create a git commit after each migration runs. Alias: `-C`.
</ParamField>

<ParamField query="--commit-prefix" type="string" default="&#x22;chore: [nx migration] &#x22;">
  Custom prefix for commit messages when `--create-commits` is enabled. Requires `--create-commits`.
</ParamField>

<ParamField query="--interactive" type="boolean" default="false">
  Enable interactive prompts to confirm whether to collect optional package updates and migrations.
</ParamField>

<ParamField query="--exclude-applied-migrations" type="boolean" default="false">
  Exclude migrations that should have already been applied in earlier updates. Must be used with `--from`.
</ParamField>

<ParamField query="--verbose" type="boolean">
  Print additional information about the migration process.
</ParamField>

## Examples

<CodeGroup>
  ```bash Migrate to latest Nx theme={null}
  nx migrate latest
  ```

  ```bash Migrate to a specific version theme={null}
  nx migrate @nx/workspace@20.0.0
  ```

  ```bash Apply migrations from the generated file theme={null}
  nx migrate --run-migrations
  ```

  ```bash Apply migrations from a custom file theme={null}
  nx migrate --run-migrations=other-migrations.json
  ```

  ```bash Create a commit after each migration theme={null}
  nx migrate --run-migrations --create-commits
  ```

  ```bash Custom commit prefix theme={null}
  nx migrate --run-migrations --create-commits --commit-prefix="chore(nx): migrate "
  ```

  ```bash Override source versions for migration computation theme={null}
  nx migrate latest --from="@nx/react@18.0.0,@nx/js@18.0.0"
  ```

  ```bash Run migrations only if the file exists theme={null}
  nx migrate --run-migrations --if-exists
  ```
</CodeGroup>

## How migrations.json works

After running `nx migrate <version>`, Nx creates (or updates) a `migrations.json` file:

```json theme={null}
{
  "migrations": [
    {
      "package": "@nx/react",
      "version": "20.0.0",
      "name": "update-react-config",
      "description": "Updates React configuration to new format",
      "cli": "nx",
      "implementation": "./src/migrations/update-20-0-0/update-react-config"
    }
  ]
}
```

You can review, reorder, or remove entries in `migrations.json` before running `--run-migrations`. Each migration is a code transform (similar to a generator) that modifies workspace files.

<Warning>
  Do not modify the generated `migrations.json` unless you understand the implications. Skipping migrations can leave the workspace in an inconsistent state.
</Warning>