How to update your app to the latest Meilisearch version

This guide walks through updating a self-hosted Meilisearch instance on DigitalOcean, AWS, or GCP when using the official Meilisearch images. The shape of the process is always the same: dump your data, swap the binary, import the dump.

Before you begin, please note the following:

• This guide does not work for versions below v0.15. Since dumps were introduced in v0.15, you’ll need to reindex all your documents and settings manually if you are on v0.14 or below
• If you are updating to v0.28 or above, keys imported from the old version will have their key and uid fields regenerated
• You’ll need to connect via SSH to your cloud instance, and depending on the user you are connecting with (root, admin, etc.), you may need to prefix some commands with sudo

If you are on v0.22 or above, the migration script automates most of what follows.

Step 1: Check your Meilisearch version

You need to know your Meilisearch version. If you don’t know or are not sure, you can use the get version endpoint:

If you get a missing_authorization_header error code, you might be on v0.24 or below. Change the authorization header to X-MEILI-API-KEY as follows:

Check your pkgVersion. If it is 0.21.0 or higher, go straight to step 3. If not, continue to the next step.

Step 2: Set all fields as displayed attributes

When creating dumps using Meilisearch versions below v0.21, all fields must be displayed in order to be saved in the dump.

First, you need to verify the displayed attributes list.

If the response includes {'displayedAttributes': '["*"]'}, you can move on to step 3.

If it's something else, save the current list to restore it after the migration is complete, and proceed to reset the list of displayed attributes to its default value ([“*”]):

This command returns an updateId. You can use this to track the status of the operation.

Once the status is processed, you're good to go.

Now that all fields are displayed proceed to the next step.

Step 3: Create the dump

Before creating your dump, make sure that your dump directory is accessible. By default, dumps are created in a folder called dumps in the configuration file directory: /var/opt/meilisearch/dumps.

You can then create a dump of your Meilisearch database:

If you are on v0.27 or below, dumps use a separate queue from the task queue. The response should return a dump uid. You can use it to track the status of the dump with the get dumps status endpoint:

Once the dump status is done, you can move on to the next step.

If you are on v0.28 or above, dumps are considered tasks and share the task queue. The response should then return a taskUid you can use to track its status with the get task endpoint:

Once the dumpCreation task shows "status": "succeeded", you're ready to move on to the next step.

Step 4: Stop the Meilisearch instance

If you haven’t done it yet, connect via SSH to your cloud instance and execute the following command to stop Meilisearch. Remember you may need to prefix it with sudo if you are not connected as root.

Step 5: Save the current binary and database for backup

Move the binary of the current Meilisearch version and the database to the tmp/ folder:

Step 6: Install the desired version of Meilisearch

You can use this command to download the Meilisearch binary. Replace {meilisearch_version} with the version of your choice formatted like this: vX.X.X.

Make the meilisearch binary executable:

Move the new Meilisearch binary to the directory containing the executable files:

Step 7: Launch Meilisearch and import the dump

Now that you’ve got the desired Meilisearch version, execute the command below to import the dump at launch.

Don’t forget to replace the dump_uid.dump with the actual dump file name.

Importing a dump requires indexing all the documents it contains. Depending on the size of your dataset, this process can take a long time and cause a spike in memory usage.

Step 8: Restart Meilisearch as a service

Once your dump has been correctly imported, press Ctrl+C to stop Meilisearch. Next, execute the command below to run the script to configure Meilisearch and restart it as a service:

Don’t forget to set displayedAttributes back to its previous value if necessary. You can do this using the update displayed attributes endpoint.

Congratulations, you have migrated your Meilisearch database to the target version.

Step 9: Clean files or rollback

Clean files

If you’ve gone through all the previous steps and Meilisearch is up and running, it’s time to do some cleanup. Remember those files we saved for backup? You can delete them with the following commands:

Since you no longer need it, you can also delete the dump file:

Rollback

If for some reason, something went wrong, you can always roll back to the previous version. Move the files back to their previous location using:

And run the configuration script:

Everything should be as it was.

I hope this guide helps you get onto a current version of Meilisearch. Our support team is always ready to help, and there is a dedicated support channel on Discord.

If you would rather not repeat this process on every release, Meilisearch Cloud applies updates for you. There is a 14-day free trial and no credit card required.

Frequently asked questions (FAQs)

How do I update a self-hosted Meilisearch instance?

Create a dump of your data, stop the instance, replace the binary with the version you want, then start Meilisearch with --import-dump pointing at the dump file. Keep the old binary and database directory until the new version is confirmed working, so you can roll back.

Do I lose my data when upgrading Meilisearch?

Not if you dump first. The database format changes between versions, so a new binary will not read an old data.ms directly. The dump is the portable representation that carries your documents and settings across the version boundary.

How long does importing a dump take?

Importing re-indexes every document, so it takes about as long as indexing that dataset from scratch and causes a spike in memory usage. Plan the maintenance window around your dataset size rather than the dump file size.

Can I roll back a failed Meilisearch upgrade?

Yes, provided you kept the previous binary and the original data.ms directory. Move both back to their original locations and re-run the setup script. This is why the guide moves them to /tmp rather than deleting them.

Do I need to do any of this on Meilisearch Cloud?

No. Cloud projects are updated for you, so there is no dump, binary swap, or import step to schedule.