Mastodon Requirements

This document is a community maintained, best effort, matrix of recent major/minor Mastodon releases and their underlying dependencies. You should always read the release notes for your version of Mastodon, and any product dependencies, before upgrading. For questions or comments please reach out to @vmstan@vmst.io.
Ruby4.34.24.14.0
3.3.x
3.2.x
3.1.x
3.0.x
2.7.x
Node.js4.34.24.14.0
22.x
20.x
18.x
16.x
14.x
Postgres4.34.24.14.0
16.x
15.x
14.x
13.x
12.x
11.x
10.x
Redis4.34.24.14.0
7.2.x
7.0.x
6.2.x
6.0.x
5.0.x
Elasticsearch4.34.24.14.0
8.x
7.x
6.x
OpenSearch4.34.24.14.0
2.x
1.x
Libvips4.34.24.14.0
8.13+
ImageMagick4.34.24.14.0
7.x
6.9.7-7+
6.x
FFmpeg4.34.24.14.0
7.x
6.x
5.x
4.x
3.x
Dependencies listed for Development versions (Alpha, Beta and Release Candidate, etc) are based on tracking the development process of the main branch on GitHub and the project Discord. These and are subject to change at any time as project requirements change.
Key
Supported in this version of Mastodon
Supported in this version, but either not explicitly or known to work with caveats
Supported in this version, but either deprecated or at end of life
Explicitly not supported in this version of by Mastodon
Not available at time of Mastodon release
Not required for this version of Mastodon

Version Chart

Mastodon Branches

Mastodon End of Life Dates

MastodonEnd of Life
4.3.xNot Yet Released
4.2.xTo Be Determined
4.1.xTo Be Determined
4.0.x & priorEnd of Life Now

Reference: Mastodon Security Policy

Additional Resources

Product Lifecycles

For the purposes of this document, when applied to dependencies the term "End of Life" is standardized to mean when there are no further updates of any kind, and/or no support available for a released version of Mastodon or it's dependencies.

Version Notes

Ruby Versions

Mastodon will have a file called .ruby-version in the source code that is the expected target version for that release. For example, this file has 3.0.6 for the Mastodon 4.1.x branch.

It is best practice to run the specific target version in this file. Administrators who require a different version will need to manually change the contents of .ruby-version to match.

It is not best practice to use the version of Ruby that is available in your OS platform repositories. You should use a tool like rbenv or rvm to install and manage the target Ruby version. The Mastodon instructions for installing from source use rbenv.

ruby -v will show your currently running Ruby version.

Node.js Versions

It is not best practice to use the version of Node.js that is available in your OS platform default repositories. NodeSource is a great option that support Debian, Ubuntu, and Redhat derivatives. This allows you to select a target major version and keep up to date with the latest patches in that version.

node -v will show your currently running Node.js version.

Use of odd-numbered Node.js releases is not reccomended due to their short release lifespans and lack of testing with Mastodon dependencies.

ImageMagick Versions

All Mastodon installs should be using at least ImageMagick 6.9.7-7 to mitigate CVE-2023-36460, see this guide for more details.

It is generally recommended to use the latest version of ImageMagick that is available in your operation system, or otherwise installable, and is supported in your version of Mastodon. This allows you to support the latest image formats and helps limit exposure to any relevant CVEs that may be associated with those products.

If you are having issues uploading, viewing or processing any of the supported image types in your Mastodon instance:

  • Make sure you're running the latest available updates to ImageMagick
  • Make sure that your default path is using the correct version
  • Make sure that your version is compiled with support for the proper media codecs

convert -version will show your currently running ImageMagick version.

The use of GraphicsMagick as an alternative to ImageMagick is not supported.

Libvips

Starting in Mastodon 4.3, the image processor will change from ImageMagick to libvips. (See PR 30090)

Libvips is generally available in most OS package repositories, but instructions on how to install it will be made available starting with the first beta release of 4.3 coming in summer of 2024. Installing libvips from most package repositories will also usually install ImageMagick as a fallback processor for formats that may not be supported by libvips, but those formats are not generally used in Mastodon. It is likely that compiling libvips from source will be the preferrable installation method.

The minimum version listed here is available as part of Debian 12 (Bookworm) and Ubuntu 24.04.

FFmpeg Versions

It is generally recommended to use the latest version of FFmpeg that is available in your operation system, or otherwise installable, and is supported in your version of Mastodon. This allows you to support the latest media codecs and helps limit exposure to any relevant CVEs that may be associated with those products.

If you are having issues uploading, viewing or processing any of the support video types or animated GIF files in your Mastodon instance:

  • Make sure you're running the latest available updates to FFmpeg
  • Make sure that your default path is using the correct version
  • Make sure that your version is compiled with support for the proper media codecs

ffmpeg -version will show your currently running ffmpeg version.

Nginx or Other Ingress

Mastodon requires an load balancer or reverse proxy to properly terminate TLS/SSL connections between users and ingress traffic to the system. Nginx is commonly used for this purpose, and an example configuration is provided in the Mastodon respository.

Other types of software can be used in place of Nginx, such as Caddy for example. There is no Mastodon specific requirement that Nginx be used.

Reguardless of the ingress software that is used, you should keep it up to date to prevent expliotation of known CVEs.

Elasticsearch 7.x is the only officially supported version at this time due to use of the Chewy gem for Ruby. Mastodon does not use any of the newer features of Elasticsearch 8.x, nor are it's Ruby gem components able to leverage them. If you're able to stay on 7.x at this time, you should.

Administrators can elect to use OpenSearch as targets for full text search indexing, with the understanding that OpenSearch is gradually diverging in API compatibility.

Redis Forks

At this time there has been no project level testing of Redis alternatives such as Valkey or Redict. While they may work fine at this time due to the limited changes since Redis changed their license in March 2024, long term support will be largely driven by the support of major Mastodon components such as Sidekiq.