Skip to content

Migrating to Mealie v1 Release

The version 1 release of Mealie should be seen as an entirely different application. A whole host of changes have been made to improve the application, performance, and developer experience. Most of these improvements required significant breaking changes in the application that made a clean and easy migration impossible. However, if you've used Mealie prior to v1 there is a migration path to get most of your data from the old version to the new v1 version.

Currently Supported Migration Data

Supporting more data is a work in progress, but not a current priority. I'm open to PR's to add support for additional data.

  • Recipes
  • Categories
  • Tags
  • Users
  • Groups
  • Meal Plans
  • Cookbooks / Pages

Migration Considerations

Before you migrate to v1.0.0-beta-x please consider the following:

API Integration Will Break

Several of the endpoints in the API have changed. This means that you will need to update your code to use the new endpoints.

Meal Plan Notifications Are Not Yet Implemented

If you're using the Meal Plan webhook feature it has yet to be implemented in v1. This feature is being significantly improved in v1 and has yet to be fully fleshed out. If you were a heavy user, you may want to wait until v1 to use this feature.

Recipes are Now Private

This can be a plus or a minus depending on your use case. If you relied on the old implementation that allowed viewing of recipes without logging in, you will loose that access. We are planning on implementing a public facing interface for groups/tenants to allow unauthenticated users to view public recipes.

Step 1: Setting Up The New Application

Given the nature of the upgrade, it is highly recommended that you standup a new instance of mealie along side your current instance. This will allow you to migrate your data safely and quickly without any issues. Follow the instructions in the Installation Checklist to get started. Once that's complete and you can login, continue here with step 2.

Step 2: Exporting Your Data from Pre-v1

In your instance of Mealie prior to v1, perform an export of your data in the Admin section. Be sure to include the recipes when performing the export. Checking additional items won't impact the migration, but they will be ignored if they are included.

Step 3: Using the Migration Tool

In your new v1 instance, navigate to /group/migrations and select "Mealie" from the dropdown selector. Upload the exported data from your pre-v1 instance. Optionally, you can tag all the recipes you've imported with the mealie_alpha tag to help you identify them. Once the upload has finished, submit the form and your migration will begin. This may take some time, but when it's complete you'll be provided a new entry in hte "Previous Migrations" table below. Be sure to review the migration report to make sure everything was successful. There may be instances where some of the recipes were not imported, but the migration will still import all the successful recipes.

In most cases, it's faster to manually migrate the recipes that didn't take instead of trying to identify why the recipes failed to import. If you're experiencing issues with the migration tool, please open an issue on GitHub.

Recipe Owners

When perform any migration, it will automatically assign the owner of the recipe to the user that performed the migration. All group members will still be able to access the recipe, however the owner has special permissions to lock the recipe from edits from other users.

Step 4: Reviewing New Features

v1 Comes with a whole host of new features and improvements. Checkout the changelog to get a sense for what's new.