---
title: "Flutter SDK 5 migration guide"
canonical_url: "https://www.nutrient.io/guides/flutter/migration-guides/flutter-5-migration-guide/"
md_url: "https://www.nutrient.io/guides/flutter/migration-guides/flutter-5-migration-guide.md"
last_updated: "2026-06-08T17:11:05.525Z"
description: "Follow this guide to update your project for Nutrient Flutter SDK 5.0 with rebranding updates."
---

We’ve rebranded the PSPDFKit Flutter SDK to Nutrient Flutter SDK to better align with our new branding. Version 5.0 marks the official transition with the complete rebranding. This guide covers all changes and provides step-by-step instructions for updating your Flutter applications. Most of your existing code will continue to work, with the exception of a few breaking changes, which are detailed below.

## Breaking changes summary

### 1. Required changes

#### Package name change

- **Old**: `pspdfkit_flutter`

- **New**: `nutrient_flutter`

**Impact**: You **must** update your `pubspec.yaml` to use the new package name.

#### Import statements

- **Old**: `import 'package:pspdfkit_flutter/pspdfkit_flutter.dart';`

- **New**: `import 'package:nutrient_flutter/nutrient_flutter.dart';`

**Impact**: You **must** update all import statements in your Dart files.

### 2. Optional changes

#### Good news: Most APIs still work

- Most existing APIs continue to work without modification

- Minimal immediate code changes required

- Old APIs are deprecated but still functional

#### When you’re ready (optional migrations)

- Migrate to the new `NutrientView` widget (from `PspdfkitWidget`)

- Migrate to the new `Nutrient` class (from `Pspdfkit`)

- Update callback parameter names

#### Additional breaking changes

- Configuration enum prefixes must be updated (e.g. `PspdfkitAppearanceMode` → `AppearanceMode`)

- Web toolbar classes now use the `Nutrient` prefix (e.g. `PspdfkitWebToolbarItem` → `NutrientWebToolbarItem`)

#### Callback parameter names (optional)

Widget callback parameter names have been simplified.

- **Old**: `onPspdfkitWidgetCreated` → **New**: `onViewCreated`

- **Old**: `onPdfDocumentLoaded` → **New**: `onDocumentLoaded`

- **Old**: `onPdfDocumentError` → **New**: `onDocumentError`

- **Old**: `onPdfDocumentSaved` → **New**: `onDocumentSaved`

**Impact**: Optional migration — old parameter names still work with deprecation warnings.

#### New widgets and classes (optional)

These are new alternatives to existing classes. The old classes still work but are deprecated.

##### Main API classes

- **Old**: `Pspdfkit` class → **New**: `Nutrient` class

- **Old**: `PspdfkitWidget` widget → **New**: `NutrientView` widget

- **Old**: `PspdfkitWidgetController` → **New**: `NutrientViewController`

##### Callback types

- **Old**: `PspdfkitWidgetCreatedCallback` → **New**: `NutrientViewCreatedCallback`

- **Old**: `PspdfkitDocumentLoadedCallback` → **New**: `NutrientDocumentLoadedCallback`

##### Web-specific classes

- **Old**: `PspdfkitWebToolbarItem` → **New**: `NutrientWebToolbarItem`

- **Old**: `PspdfkitWebAnnotationToolbarItem` → **New**: `NutrientWebAnnotationToolbarItem`

##### Platform interface classes

- **Old**: `PspdfkitFlutterPlatform` → **New**: `NutrientFlutterPlatform`

- **Old**: `PspdfkitFlutterMethodChannel` → **New**: `NutrientFlutterMethodChannel`

- **Old**: `PspdfkitFlutterWeb` → **New**: `NutrientFlutterWeb`

**Impact**: Optional migration — old classes still work with deprecation warnings.

### 3. Configuration enum prefix changes (breaking)

All configuration enum prefixes have been simplified by removing the `Pspdfkit` prefix. **This is a breaking change if you use these enums.**

> **How to check if you’re affected**: Search your codebase for `Pspdfkit` + enum names (e.g. `PspdfkitAppearanceMode`, `PspdfkitScrollDirection`). If found, you must update them.

#### Core configuration enums

- Old

- New
---

- `PspdfkitAppearanceMode.dark`

- `AppearanceMode.dark`
---

- `PspdfkitScrollDirection.horizontal`

- `ScrollDirection.horizontal`
---

- `PspdfkitPageTransition.curl`

- `PageTransition.curl`
---

- `PspdfkitSpreadFitting.fit`

- `SpreadFitting.fit`
---

- `PspdfkitUserInterfaceViewMode.automatic`

- `UserInterfaceViewMode.automatic`
---

- `PspdfkitThumbnailBarMode.floating`

- `ThumbnailBarMode.floating`
---

- `PspdfkitPageLayoutMode.single`

- `PageLayoutMode.single`
---

- `PspdfkitAutoSaveMode.immediate`

- `AutoSaveMode.immediate`
---

- `PspdfkitToolbarPlacement.top`

- `ToolbarPlacement.top`
---

- `PspdfkitZoomMode.fitToWidth`

- `ZoomMode.fitToWidth`
---

- `PspdfkitToolbarMenuItems.searchButtonItem`

- `ToolbarMenuItems.searchButtonItem`
---

- `PspdfkitSidebarMode.annotations`

- `SidebarMode.annotations`
---

- `PspdfkitWebInteractionMode.ink`

- `NutrientWebInteractionMode.ink`
---

- `PspdfkitWebToolbarItemType.zoom`

- `NutrientWebToolbarItemType.zoom`
---

- `PspdfkitWebAnnotationToolbarItemType.note`

- `NutrientWebAnnotationToolbarItemType.note`

#### Signature and form enums

- Old

- New
---

- `PspdfkitShowSignatureValidationStatusMode.ifSigned`

- `ShowSignatureValidationStatusMode.ifSigned`
---

- `PspdfkitSignatureSavingStrategy.alwaysSave`

- `SignatureSavingStrategy.alwaysSave`
---

- `PspdfkitSignatureCreationMode.draw`

- `SignatureCreationMode.draw`
---

- `PspdfkitAndroidSignatureOrientation.portrait`

- `NutrientAndroidSignatureOrientation.portrait`

**Impact**: **Breaking change** — old enum prefixes have been removed. You must update your code if you use these enums.

#### Package deprecation (breaking)

- **Old package**: `pspdfkit_flutter` is now officially deprecated

- **New package**: `nutrient_flutter` is the only supported package

- **Migration timeline**: While the old package may still work temporarily, it will no longer receive updates

**Impact**: **You must migrate to `nutrient_flutter` for continued support and updates.**

#### API priority changes (breaking)

- **Old APIs**: Now marked as deprecated with stronger warnings

- **New APIs**: Promoted to primary status

- **Future compatibility**: Old APIs may be removed in future versions

**Impact**: **Plan to migrate to new APIs within the next few releases.**

## Migration steps

### Automated migration (recommended)

We provide a migration script that automatically updates your project. This is the fastest and most reliable way to migrate:

```bash

# Download and run the migration script.

curl -O https://raw.githubusercontent.com/PSPDFKit/pspdfkit-flutter/refs/heads/master/tools/migrate_to_nutrient.dart

# Or if you've cloned the repository.

dart path/to/pspdfkit-flutter/tools/migrate_to_nutrient.dart

```

#### Migration script options

- `--dry-run`: Preview changes without modifying files

- `--update-apis`: Also update class names and enum prefixes (Pspdfkit → Nutrient, PspdfkitWidget → NutrientView, etc.)

- `--help`: Show usage information

#### What the script does

1. Updates the `pubspec.yaml` dependency from `pspdfkit_flutter` to `nutrient_flutter`.

2. Updates all import statements in `.dart` files.

3. Optionally updates API class names (with the `--update-apis` flag):
   - `Pspdfkit` → `Nutrient`
   - `PspdfkitWidget` → `NutrientView`
   - `PspdfkitWidgetController` → `NutrientViewController`
   - Enum prefixes: `PspdfkitAppearanceMode.` → `AppearanceMode.`
   - Enum prefixes: `PspdfkitScrollDirection.` → `ScrollDirection.`
   - Enum prefixes: `PspdfkitPageTransition.` → `PageTransition.`
   - Enum prefixes: `PspdfkitSpreadFitting.` → `SpreadFitting.`
   - Enum prefixes: `PspdfkitUserInterfaceViewMode.` → `UserInterfaceViewMode.`
   - Enum prefixes: `PspdfkitThumbnailBarMode.` → `ThumbnailBarMode.`
   - Enum prefixes: `PspdfkitPageLayoutMode.` → `PageLayoutMode.`
   - Enum prefixes: `PspdfkitAutoSaveMode.` → `AutoSaveMode.`
   - Enum prefixes: `PspdfkitToolbarPlacement.` → `ToolbarPlacement.`
   - Enum prefixes: `PspdfkitZoomMode.` → `ZoomMode.`
   - Enum prefixes: `PspdfkitToolbarMenuItems.` → `ToolbarMenuItems.`
   - Enum prefixes: `PspdfkitSidebarMode.` → `SidebarMode.`
   - Enum prefixes: `PspdfkitShowSignatureValidationStatusMode.` → `ShowSignatureValidationStatusMode.`
   - Enum prefixes: `PspdfkitSignatureSavingStrategy.` → `SignatureSavingStrategy.`
   - Enum prefixes: `PspdfkitSignatureCreationMode.` → `SignatureCreationMode.`
   - Enum prefixes: `PspdfkitAndroidSignatureOrientation.` → `NutrientAndroidSignatureOrientation.`
   - Enum prefixes: `PspdfkitWebInteractionMode.` → `NutrientWebInteractionMode.`
   - Web classes: `PspdfkitWebToolbarItem` → `NutrientWebToolbarItem`
   - Web enums: `PspdfkitWebToolbarItemType.` → `NutrientWebToolbarItemType.`
   - Web annotation classes: `PspdfkitWebAnnotationToolbarItem` → `NutrientWebAnnotationToolbarItem`
   - Web annotation enums: `PspdfkitWebAnnotationToolbarItemType.` → `NutrientWebAnnotationToolbarItemType.`
   - Callback types: `PspdfkitWidgetCreatedCallback` → `NutrientViewCreatedCallback`
   - Callback parameters: `onPspdfkitWidgetCreated` → `onViewCreated`
   - Callback parameters: `onPdfDocumentLoaded` → `onDocumentLoaded`
   - Callback parameters: `onPdfDocumentError` → `onDocumentError`
   - Callback parameters: `onPdfDocumentSaved` → `onDocumentSaved`
   - Callback methods: `Nutrient.pspdfkitDocumentLoaded` → `Nutrient.documentLoaded`

4. Preserves your code structure and formatting.

5. Shows a summary of changes made.

#### Example usage

```bash

# Preview changes first.

dart migrate_to_nutrient.dart --dry-run

# Apply migration with new imports.

dart migrate_to_nutrient.dart

# Full migration including API updates.

dart migrate_to_nutrient.dart --update-apis

# Migrate specific directory.

dart migrate_to_nutrient.dart lib/

# Combine options.

dart migrate_to_nutrient.dart --dry-run --update-apis

```

### Manual migration steps

If you prefer to migrate manually or need more control over the process, follow the steps outlined below.

#### Step 1 — Update pubspec.yaml

Replace the dependency in your `pubspec.yaml` file:

```diff

dependencies:

- pspdfkit_flutter: ^4.4.1

+ nutrient_flutter: ^5.0.0

```

#### Step 2 — Update import statements

```diff

- import 'package:pspdfkit_flutter/pspdfkit_flutter.dart';

+ import 'package:nutrient_flutter/nutrient_flutter.dart';

```

#### Step 3 — Update widget usage

```diff

- PspdfkitWidget(

+ NutrientView(
    documentPath: 'path/to/document.pdf',
    configuration: configuration,

-   onPspdfkitWidgetCreated: (PspdfkitWidgetController controller) {

+   onViewCreated: (NutrientViewController controller) {
      // Handle controller.
    },
  )

```

#### Step 4 — Update plugin initialization

```diff

- await Pspdfkit.initialize(

+ await Nutrient.initialize(
    androidLicenseKey: "YOUR_ANDROID_LICENSE_KEY",
    iosLicenseKey: "YOUR_IOS_LICENSE_KEY",
    webLicenseKey: "YOUR_WEB_LICENSE_KEY",
  );

```

#### Step 5 — Update method calls

```diff

- await Pspdfkit.present('path/to/document.pdf');

+ await Nutrient.present('path/to/document.pdf');

```

## Compatibility matrix

- Component

- Old

- New

- Status
---

- Package name

- `pspdfkit_flutter`

- `nutrient_flutter`

- ⚠️ Use `nutrient_flutter`
---

- Main widget

- `PspdfkitWidget`

- `NutrientView`

- ✅ Both work
---

- Controller

- `PspdfkitWidgetController`

- `NutrientViewController`

- ✅ Both work
---

- Plugin class

- `Pspdfkit`

- `Nutrient`

- ✅ Both work
---

- Import

- `pspdfkit_flutter.dart`

- `nutrient_flutter.dart`

- ✅ Both work

## Important notes

### Backward compatibility

- **Most existing APIs continue to work**; there are minimal breaking changes.

- Old APIs are marked as `@Deprecated` but remain functional.

- You can migrate gradually at your own pace.

- **Exception**: Enum prefixes are breaking changes and must be updated.

### Deprecation timeline

- **Current (v5.0.0)**: Old APIs deprecated but functional

- **Future versions**: Old APIs will be removed (timeline TBD)

### For new projects

- Use the new `nutrient_flutter` package and `NutrientView` widget.

- Follow the new import patterns and class names from the start.

### For existing projects

- Continue using old APIs temporarily if needed.

- We recommend migrating to new APIs for future compatibility.

- Update package dependency to `nutrient_flutter`.

## Common migration issues and solutions

### Issue 1 — Import resolution errors

**Problem**: The IDE shows “package not found” errors after changing the package name.

**Solution**:

1. Run `flutter clean`.

2. Run `flutter pub get`.

3. Restart your IDE.

4. If using VS Code, reload the window (Cmd/Ctrl + Shift + P → "Developer: Reload Window").

### Issue 2 — Mixed API usage warnings

**Problem**: Deprecation warnings when using both old and new APIs.

**Solution**: Use consistent API style throughout your app.

```dart

// ❌ Don't mix old and new APIs.
import 'package:nutrient_flutter/nutrient_flutter.dart';
await Pspdfkit.initialize(); // Will show deprecation warning

// ✅ Use consistent API style.
import 'package:nutrient_flutter/nutrient_flutter.dart';
await Nutrient.initialize(); // Recommended

```

### Issue 3 — Type casting errors

**Problem**: Type casting fails between old and new controller types.

**Solution**:

```dart

// ❌ Don't cast between different controller types.
NutrientViewController controller = widget.controller as NutrientViewController;

// ✅ Use appropriate controller type for your widget.
NutrientView(
  onViewCreated: (NutrientViewController controller) {
    // Use `NutrientViewController` here.
  },
)

PspdfkitWidget(
  onPspdfkitWidgetCreated: (PspdfkitWidgetController controller) {
    // Use `PspdfkitWidgetController` here.
  },
)

```

## Additional resources

- [Nutrient Flutter documentation](https://www.nutrient.io/guides/flutter.md)

- [Support](https://support.nutrient.io/hc/en-us/requests/new)

## Changelog

Refer to our [changelog](https://www.nutrient.io/guides/flutter/changelog.md) for a detailed version history and a list of all the changes in the rebranding release.

### Migration checklist

- ☑️ Update the `pubspec.yaml` dependency

- ☑️ Run `flutter pub get`

- ☑️ Update import statements

- ☑️ Test app functionality

- ☑️ Gradually migrate APIs (optional)

- ☑️ Update tests

## Conclusion

This migration guide covers the major changes in the rebranding from PSPDFKit to Nutrient. For the most up-to-date information, refer to the official documentation at [nutrient.io](https://www.nutrient.io/guides/).

🎉 You’re all set! Your app should now be using the new Nutrient Flutter SDK while maintaining full compatibility with your existing code.
---

## Related pages

- [Flutter 1 10 4 Migration Guide](/guides/flutter/migration-guides/flutter-1-10-4-migration-guide.md)
- [Flutter 3 3 Migration Guide](/guides/flutter/migration-guides/flutter-3-3-migration-guide.md)
- [Flutter SDK 3 migration guide](/guides/flutter/migration-guides/flutter-3-migration-guide.md)
- [Flutter 3 12 Migration Guide](/guides/flutter/migration-guides/flutter-3-12-migration-guide.md)
- [Flutter 3 6 Migration Guide](/guides/flutter/migration-guides/flutter-3-6-migration-guide.md)
- [Flutter 3 2 Migration Guide](/guides/flutter/migration-guides/flutter-3-2-migration-guide.md)
- [Flutter 3 9 Migration Guide](/guides/flutter/migration-guides/flutter-3-9-migration-guide.md)
- [Flutter SDK 4 migration guide](/guides/flutter/migration-guides/flutter-4-migration-guide.md)
- [Upgrade to the latest Flutter version](/guides/flutter/migration-guides/upgrading.md)
- [Flutter SDK 4.2 migration guide](/guides/flutter/migration-guides/flutter-4-2-migration-guide.md)