This document is a best-effort, community maintained, support matrix of recent Mastodon releases and their underlying dependencies. It is designed to provide high-level guidance for determining upgrade paths, and what to deploy in an environment. Administrators should also consult the the release notes for your version of Mastodon, and any product dependencies, before upgrading.
For questions, comments or concerns please reach out to @[email protected].
Lifecycles
Matrix
The four most recent branches of Mastodon are listed across the top of each table. 4.4/Dev, 4.3/Release, 4.2/Previous, 4.1/EOL. The version of each required component is on the left side of the table.
Any dependencies listed for development versions (nightly/alpha) of Mastodon 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.Ruby
| 4.4 | 4.3 | 4.2 | 4.1 | |
| 3.4 | ||||
| 3.3 | ||||
| 3.2 | ||||
| 3.1 | ||||
| 3.0 | ||||
| 2.7 |
Mastodon has file called
.ruby-version in the source code that is the expected target version for that release.
You should use rbenv to install and manage the target Ruby version.The official Mastodon container image will always use the correct target version of Ruby for that release.
Node.js
| 4.4 | 4.3 | 4.2 | 4.1 | |
| 24.x | ||||
| 23.x | ||||
| 22.x | ||||
| 20.x | ||||
| 18.x | ||||
| 16.x | ||||
| 14.x |
Mastodon will have a file called
.nvmrc in the source code that is the expected target version for that release.
You should use nvm to install and manage the target Node version.Odd numbered Node.js releases should be used with caution and are recommended for use only by experienced administrators who are willing/able to provide feedback.
The official Mastodon container image will always use the correct target version of Node for that release.
Postgres
| 4.4 | 4.3 | 4.2 | 4.1 | |
| 17.x | ||||
| 16.x | ||||
| 15.x | ||||
| 14.x | ||||
| 13.x | ||||
| 12.x | ||||
| 11.x | ||||
| 10.x |
Always use caution when moving between major versions of Postgres (ex: 15.x to 16.x) as failure to adequately plan this migration may result in data-loss!
Cache
| Redis | 4.4 | 4.3 | 4.2 | 4.1 |
| 8.0 | ||||
| 7.4 | ||||
| 7.2 | ||||
| 7.0 | ||||
| 6.2 | ||||
| 6.0 | ||||
| 5.0 | ||||
| Dragonfly | 4.4 | 4.3 | 4.2 | 4.1 |
| 1.27 | ||||
| 1.26.3+ | ||||
| Valkey | 4.4 | 4.3 | 4.2 | 4.1 |
| 8.1 | ||||
| 8.0 |
Redis is the only fully-supported in-memory database/cache.
Search
| Elasticsearch | 4.4 | 4.3 | 4.2 | 4.1 |
| 8.x | ||||
| 7.x | ||||
| OpenSearch | 4.4 | 4.3 | 4.2 | 4.1 |
| 2.x |
Elasticsearch 7.x is the only fully-supported full text search index.
Elasticsearch 8.x (which still has the Mastodon-required 7.x APIs) or OpenSearch (an API-compatible Elasticsearch 7.x fork) should be used with caution and are recommended for use only by experienced administrators who are willing/able to provide feedback.
Images
| libvips | 4.4 | 4.3 | 4.2 | 4.1 |
| 8.16 | ||||
| 8.15 | ||||
| 8.14 | ||||
| 8.13 | ||||
| ImageMagick | 4.4 | 4.3 | 4.2 | 4.1 |
| 7.1 | ||||
| 7.0 | ||||
| 6.9.7-7+ | ||||
| 6.x |
Mastodon is transitioning from ImageMagick to libvips starting with Mastodon 4.3, which provides better performance.
Unless you are unable to run libvips 8.13+ on your system, you should switch from ImageMagick as soon as possible.
Support for ImageMagick will be removed in an upcoming release.
The official Mastodon container images use libvips.
All Mastodon installs using still using ImageMagick should run at least 6.9.7-7 to mitigate CVE-2023-36460, see this guide for more details.
FFmpeg
| 4.4 | 4.3 | 4.2 | 4.1 | |
| 7.1 | ||||
| 7.0 | ||||
| 6.1 | ||||
| 5.1 | ||||
| 4.4 | ||||
| 4.3 | ||||
| 4.2 | ||||
| 3.4 |
If you do not see a major/minor version of it listed in the matrix, it is considered end of life.
While it may continue to work, it may contain known issues including security vulnerabilities.
Refer to endoflife.date for more information on determining if your version of FFmpeg is considered supported.
Ingress
Mastodon requires a 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.
There are no specific version requirements for Nginx, and other types of software can be used in place of Nginx, such as Caddy for example.
Reguardless of the ingress software that is used, you should keep it up to date to prevent expliotation of known security vulnerabilities.
Key
| Key | |
|---|---|
| Supported in this version | |
| Supported with some caveats | |
| Supported but deprecated or at end of life | |
| Not supported in this version | |
| Not available for this version | |
| Not required for this version |
End of Life
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.
| Mastodon | Status | |
|---|---|---|
| 4.4.x | Development Branch | |
| 4.3.x | Supported Release | |
| 4.2.x | Supported Release | |
| 4.1.x & prior | End of Life |
Reference: Mastodon Security Policy
End of Life versions of Mastodon do not receive any features, bug fixes, and generally no security updates except at the discretion of the core development team.