FreeRTOS/FreeRTOS: the classic distribution, its submodules and its demos

What the FreeRTOS/FreeRTOS repository is, and who it is for

FreeRTOS is a real-time kernel for microcontrollers, and this repository is the distribution that wraps it. The README describes it as the "'Classic' FreeRTOS distribution", started as a Git clone of the SourceForge SVN repository, with the kernel brought in as a submodule. So the thing you clone is not just a scheduler: it is the kernel, a set of supplementary libraries, and a large collection of example projects.

The audience is narrow and specific. You are writing firmware for a microcontroller, you need deterministic task scheduling, and you have decided not to write your own scheduler. The repository assumes you already have a toolchain for your target and that you know which compiler you are using, because the demos are pre-configured per hardware platform and per compiler. If you are looking for something to run on a Linux host as a learning exercise, the Windows simulator demos mentioned in the release notes are the closest thing, and they are demos rather than a supported product.

What this repository is not: it is not the kernel itself. The kernel source lives in FreeRTOS/Source, which the README says is submoduled from the FreeRTOS-Kernel repository. If your interest is the scheduler alone, this distribution carries a lot of extra weight.

How the distribution is laid out and how components flow into a build

The repository structure is the mechanism, and it is worth understanding before you clone. Four directories matter. FreeRTOS/Source holds the kernel. FreeRTOS/Demo holds pre-configured example projects that demonstrate the kernel on different hardware and with different compilers. FreeRTOS-Plus/Source holds additional component libraries and select partner libraries, with further readme files in the subdirectories. FreeRTOS-Plus/Demo holds examples that combine the kernel with those libraries.

The data flow is a submodule checkout followed by a build. The top level of the repository carries .gitmodules, and the components referenced there are separate Git repositories. When you clone with submodules, Git checks out a specific commit of each component into its subdirectory. Your build then compiles the kernel sources from FreeRTOS/Source together with whichever library sources you need from FreeRTOS-Plus/Source, plus your application code.

The release notes show how tightly the components are versioned together. The 202411.00 release updates the kernel, FreeRTOS+TCP, coreMQTT, corePKCS11, coreHTTP, coreJSON, AWS IoT Over-the-air-Updates, Device Shadow, Jobs, Device Defender, Backoff Algorithm, Fleet Provisioning, coreSNTP, SigV4 and the Cellular Interface to their 202406-LTS versions, moves coreMQTT Agent to v1.3.0 and MbedTLS to v3.5.1. That is the trade-off: you get a tested combination, but you do not get to pick arbitrary versions of individual libraries without leaving the distribution.

Installing it and starting from a demo

The README is explicit that this repository uses Git submodules and that downloading the ZIP from the GitHub UI will not give you the submodule contents. It also notes the ZIP is not a valid git repository. So the install path is a clone with the recursion flag.

git clone https://github.com/FreeRTOS/FreeRTOS.git --recurse-submodules

An SSH variant is given as well:

git clone [email protected]:FreeRTOS/FreeRTOS.git --recurse-submodules

If you already cloned without the flag, the README gives the repair command:

git submodule update --init --recursive

On Windows there is an extra step, because the repository and its submodules contain symbolic links. The README says to set core.symlinks to true:

git config --global core.symlinks true

It further states that you must either enable Developer Mode or run any git command that writes to the system from an elevated console, otherwise symbolic links are written as ordinary files containing the link path as text. That is a real failure mode, not a formality: a build that follows a text file instead of a symlink will not compile.

After cloning, the first real use is to open a project under FreeRTOS/Demo that matches your hardware and compiler. The README does not enumerate them; it points to the FreeRTOS.org website for the kernel quick start guide, the list of supported devices and compilers, and the API reference. There is no single build command for the whole repository, and the README does not provide one.

Where this distribution gets in the way

The submodule design is the main cost. Every component is pinned to a commit, and moving one component forward means either updating the submodule pointer or replacing the submodule with your own copy. The README does not document rollback, and it does not describe how to mix a newer kernel with an older library set. If your product needs a kernel fix that landed after the last LTS sync, you are outside the tested combination.

The release cadence reinforces this. The listed releases are 202411.00 from 2024-11-21, 202212.01 from 2023-03-03 and 202212.00 from 2022-12-10. The last push to the repository was on 2026-08-26, so the repository is not archived, but the release tags move far more slowly than the branch does. Anyone treating the main branch as a supported release is making an assumption the release notes do not support.

There is also a licensing spread to be aware of. The repository is MIT, and the README lists MbedTLS and WolfSSL among the updated components. Those are third-party libraries with their own terms, and the README does not restate them. The LICENSE.md file at the top level is the place to look, but the components pulled in as submodules carry their own licences, and that is where a compliance check has to happen.

Finally, the CBMC proofs in FreeRTOS/Test/CBMC/proofs are model-checking artifacts. The README says you need to install CBMC and other tools to run them. They are not part of a normal firmware build, and they do not run as part of one.

FreeRTOS versus Zephyr, and versus the kernel on its own

The most common comparison is with Zephyr, and the difference is structural rather than a matter of features. FreeRTOS/FreeRTOS is a kernel plus a set of libraries that you assemble into a project you configure yourself, with per-board demos as the starting point. Zephyr is built around a single tree with a Kconfig and devicetree based configuration system and a unified build tool. If you want one build system to describe your board and your drivers, that model is the reason people choose it. If you want to drop a small scheduler into an existing vendor IDE project, the FreeRTOS model fits better, because a demo project is already a vendor IDE project.

The other alternative is inside the same project: clone FreeRTOS-Kernel instead of this distribution. The README states plainly that FreeRTOS/Source is submoduled from that repository, so the kernel is the same code. What you give up is FreeRTOS-Plus/Source, the LTS library set, and the demo projects. If your application needs only tasks, queues and semaphores, the smaller clone is easier to vendor and easier to audit. If you need coreMQTT or FreeRTOS+TCP, the umbrella repository saves you from assembling compatible versions yourself.

Maintenance, upgrades and licence handling

Upgrading means moving between release tags, not pulling the main branch. The README points to the Releases page for older releases, and the release notes describe each tag as a coordinated update of the kernel and the LTS libraries. The jump from 202212.00 to 202411.00 is not small: it moves MbedTLS from v3.2.1 to v3.5.1, brings coreMQTT Agent to v1.3.0, and adds new demo targets including ARMv7-R No_GIC, ARMv7-R MPU and a FreeRTOS_Plus_TCP_IPv6_Demo Windows simulator demo. The 202212.00 notes also record that all demos depending on coreMQTT were updated to work with coreMQTT v2.X.X, which is the kind of change that reaches into application code.

Budget for that. An upgrade is a re-validation of your application against a new library set, not a version bump. The repository gives you no migration guide beyond the release notes and the Upgrading-to-FreeRTOS.url link at the top level.

On licensing, the repository is MIT. That covers the files in this repository, but the submodules are separate projects, and MbedTLS and WolfSSL in particular are third-party components with their own terms. The README does not summarise them. Read LICENSE.md and then read the licence file inside each submodule you actually ship. This is a description of where the terms live, not legal advice.

Editorial conclusion

Adopt FreeRTOS/FreeRTOS if you want the kernel together with the LTS libraries and a pre-configured demo for your board, and if you are comfortable working with a repository whose components live in submodules. Do not adopt it if you only need the scheduler: clone FreeRTOS-Kernel directly instead. Before committing, verify that your target appears in the list of supported devices and compilers on freertos.org, and confirm that FreeRTOS/Demo contains a project for your toolchain. Then check whether the library versions in the 202411.00 release match what your product needs, because the release notes pin coreMQTT Agent to v1.3.0 and MbedTLS to v3.5.1.

Frequently asked questions

Official sources

1. FreeRTOS/FreeRTOS on GitHub
2. License: MIT
3. Project website
4. README
5. Releases