---
title: "Upgrade Guide"
description: "Learn how to migrate between Unhead versions in Nuxt."
canonical_url: "https://unhead.unjs.io/docs/nuxt/head/guides/get-started/migration"
last_updated: "2026-08-16T19:32:06.057Z"
---

## Migrate to v3 (from v2)

This section applies only if your Nuxt app or module directly installs Unhead v3. Nuxt manages its own Unhead dependency, so do not force-upgrade Nuxt's transitive copy.

<tip>

Nuxt handles most Unhead integration automatically. Most Nuxt users will only be affected by the legacy property name changes.

</tip>

### Legacy Property Names

🚦 Impact Level: High

Current Unhead entry points omit `DeprecationsPlugin`. Rename these properties in code that directly uses Unhead v3. Nuxt may retain compatibility while upgrading its bundled version.

**children → innerHTML**

```diff
useHead({
  script: [{
-   children: 'console.log("hello")',
+   innerHTML: 'console.log("hello")',
  }]
})
```

**hid / vmid → key**

```diff
useHead({
  meta: [{
-   hid: 'description',
+   key: 'description',
    name: 'description',
    content: 'My description'
  }]
})
```

**body: true → tagPosition: 'bodyClose'**

```diff
useHead({
  script: [{
    src: '/script.js',
-   body: true,
+   tagPosition: 'bodyClose',
  }]
})
```

### Schema.org Plugin

🚦 Impact Level: Medium

If you're using `@unhead/schema-org` directly (not through `nuxt-schema-org`), the plugin exports have changed:

```diff
- import { SchemaOrgUnheadPlugin } from '@unhead/schema-org/vue'
+ import { UnheadSchemaOrg } from '@unhead/schema-org/vue'
```

<note>

If you're using the `nuxt-schema-org` module, no changes are needed.

</note>

### Server Composable Aliases Deprecated

🚦 Impact Level: Low

The `useServerHead`, `useServerHeadSafe`, and `useServerSeoMeta` names are deprecated compatibility aliases in the Vue adapter. Use the standard composables instead.

```diff
- useServerSeoMeta({ description: 'My description' })
+ useSeoMeta({ description: 'My description' })
```

If you need server-only head management:

```ts
if (import.meta.server) {
  useHead({ title: 'Server Only' })
}
```

### Hooks

🚦 Impact Level: Low

If you're using Unhead hooks directly, the `init` hook was removed. `dom:renderTag` is deprecated and no longer called internally. `dom:rendered` is deprecated but still emitted; prefer the `onRendered` option on `useHead()`. Both `dom:beforeRender` and `renderDOMHead()` are now synchronous.

---

## Migrate to v2 (from v1)

[Nuxt 3.16 upgraded its built-in head manager to Unhead v2](https://nuxt.com/blog/v3-16). Nuxt 3 uses a compatibility build, so most applications can upgrade without changing head calls.

### Nuxt v4 Migration

Follow the official [Nuxt v4 migration guide](https://nuxt.com/docs/4.x/getting-started/upgrade#migrating-to-nuxt-4).

### Key Changes

Nuxt handles these v2 integration changes:

- **Client/server subpath exports:** Nuxt configures these automatically
- **Implicit context:** Nuxt manages Vue context integration
- **Template params and plugins:** Nuxt includes the necessary plugins

For the full list of changes, check out the [Vue Upgrade Guide](/docs/vue/head/guides/get-started/migration).