LibreELEC
LibreELEC is a lightweight, open-source Linux distribution designed as a "just enough OS" specifically for running the Kodi media center software on embedded devices, single-board computers, and personal computers.[1] It focuses on providing a minimalistic environment that prioritizes performance and simplicity, booting directly into Kodi without unnecessary desktop components or bloat.[1] Originating as a fork of the discontinued OpenELEC project, LibreELEC was established in March 2016 following internal disagreements within the OpenELEC team over change management and project maintenance that began in 2015.[2] The name "LibreELEC" emphasizes freedom in development practices while maintaining open-source principles under the GPLv2 license, allowing users to clone, modify, and distribute the codebase freely.[1] Developed by a volunteer team and supported by community contributions, it continues the numbering scheme from OpenELEC starting at version 7.0.0, with the latest stable release being LibreELEC 12.2.1 in November 2025, featuring Kodi 21.3 (Omega) and platform-specific Linux kernels such as 6.12.x for Raspberry Pi and 6.16.x for x86 systems.[3][4][5] LibreELEC supports a wide range of hardware platforms, including Raspberry Pi models (from Pi 2 to Pi 5), x86_64 PCs and NUCs, Amlogic-based devices, and Rockchip systems, with images optimized for efficient media playback and low resource usage.[6] Key features include automatic updates, a USB-SD Creator tool for easy installation, and integration with add-ons for enhanced functionality like ambient lighting via HyperHDR.[6] The project encourages community involvement through its forum and GitHub repository, ensuring ongoing improvements in hardware compatibility and Kodi integration.[1]Introduction
Overview
LibreELEC is a non-profit, open-source Linux distribution that functions as a "Just Enough Operating System" (JEOS), designed specifically to run the Kodi media center software with minimal system overhead.[7][8] It embeds Kodi as the primary application, providing an efficient platform for media playback on dedicated devices without unnecessary desktop environments or extraneous services.[9] Originally forked from OpenELEC, LibreELEC emphasizes simplicity and performance for home entertainment setups.[10] The system boots directly into Kodi, stripping away traditional OS bloat to prioritize low latency and resource efficiency during media streaming and playback.[8] It supports both x86/x64 and ARM architectures, enabling deployment across a range of consumer hardware. As of November 2025, the latest stable release is version 12.2.1, incorporating Kodi 21.3 "Omega" and platform-specific Linux kernels such as 6.16.x for x86_64 and 6.12.x for Raspberry Pi.[3][5][4] LibreELEC targets compact devices such as mini PCs, Raspberry Pi boards, and Android TV boxes powered by Amlogic or Rockchip SoCs, making it ideal for home theater PCs (HTPCs) and single-board computer projects.[6][4] The entire distribution is fully open-source, licensed under the GNU General Public License version 2 (GPLv2) along with other compatible open-source licenses for its components.[11]Design principles
LibreELEC embodies a minimalist design philosophy as a "just enough operating system" (JeOS) tailored exclusively for Kodi, incorporating only essential components such as the Linux kernel, hardware drivers, BusyBox utilities, and Kodi media center software while deliberately excluding desktop environments, office suites, or other extraneous applications to reduce overhead and enhance performance on resource-constrained devices.[11] This approach enables operation on hardware with minimal specifications; LibreELEC 10.0 and later versions require at least 1 GB of RAM.[12] The result is rapid boot times, often achieving the Kodi interface in approximately 20-25 seconds, prioritizing immediate media playback over general-purpose computing capabilities.[13] Central to its architecture is modularity, achieved through a read-only SquashFS root filesystem that ensures system integrity by preventing runtime modifications to core files, complemented by writable overlay filesystems for user data, configurations, and add-ons stored on persistent storage like SD cards or USB drives.[14] This structure supports seamless over-the-air (OTA) updates within the same major release series, downloading and applying patches automatically without requiring full reinstallations, thereby maintaining stability while delivering bug fixes and enhancements.[15] Security and stability are bolstered by the immutable root filesystem, which mitigates risks from misconfigurations or malware by isolating user changes, alongside a single-user (root) model with configurable passwords and optional service controls for SSH, Samba, and firewall via the settings add-on.[14] Kernel and driver updates are synchronized with Kodi release cycles, as seen in LibreELEC 12.2 integrating platform-specific Linux kernels (such as 6.16 for x86_64) alongside Kodi 21.3, ensuring hardware compatibility and timely security patches without introducing breaking changes.[16][5] The overall ethos promotes a "set it and forget it" experience, minimizing user intervention for routine operation on dedicated media hardware. Optimization for embedded systems is facilitated by a custom project-based build system using shell scripts and tools like crosstool-NG for cross-compilation across architectures such as ARM, x86, and RPi, allowing tailored images for specific devices.[11] Hardware acceleration is natively supported through APIs including VAAPI for Intel/AMD GPUs, VDPAU for NVIDIA, and V4L2 for ARM-based systems like Raspberry Pi, offloading video decoding to dedicated GPU hardware to achieve efficient playback of high-resolution content on low-power processors.[17] At its core, LibreELEC's philosophy centers on upstream fidelity to Kodi's development roadmap rather than proprietary extensions, fostering longevity as a lightweight fork that evolved from OpenELEC's JeOS model to sustain focused media center reliability in a community-driven ecosystem.[11]History
Origins and fork from OpenELEC
OpenELEC, founded in 2009, was developed as a lightweight, embedded Linux distribution optimized for running XBMC, the predecessor to the Kodi media center software.[18] Designed as a "just enough OS" to minimize resource usage and boot quickly into a media playback environment, it gained popularity for home theater PCs and single-board computers. By 2015, OpenELEC had advanced to version 6.0, incorporating Kodi 15 (Isengard) and updates to core components like the Linux kernel, but the project encountered increasing maintenance challenges, including infrastructure upkeep and internal disagreements over development practices.[19] In March 2016, a group of more than 25 active OpenELEC developers, frustrated by creative differences regarding change management, maintenance priorities, and overall project direction, announced a fork to create LibreELEC.[20] These differences stemmed from conflicts with OpenELEC founder Stephan Raue (@sraue), who envisioned the project as a personal hobby and remained with the original codebase, while the forking team sought a more structured, community-oriented approach.[2] The name "LibreELEC" emphasized principles of freedom in project governance, alongside a commitment to open-source software, distinguishing it from OpenELEC's evolving ties to commercial partners like WeTek.[21] The initial goals of LibreELEC focused on delivering stable, timely updates synchronized with Kodi release cycles to overcome OpenELEC's perceived stagnation, while operating as a non-profit initiative free from commercial influences.[2] First alpha builds emerged in late March 2016, prioritizing community-driven development and rapid iteration to revive the lightweight OS concept.[22] OpenELEC ceased active development around 2017 following the fork, with its final major release being version 8.0, leaving LibreELEC as the de facto successor and primary maintainer of the lightweight Kodi ecosystem.[19]Major releases and milestones
LibreELEC's release numbering began with version 7.0.0 in April 2016, adopting OpenELEC's established scheme to maintain continuity while aligning closely with Kodi versions.[23][24] This initial release incorporated Kodi 16.1 "Jarvis," focusing on stability for embedded devices like the Raspberry Pi and providing a lightweight foundation for media playback.[23] Subsequent major releases have synchronized with Kodi's development cycles, introducing enhancements in hardware support, kernel updates, and system optimizations. Version 8.0, released in February 2017, integrated Kodi 17.0 "Krypton" and emphasized improved ARM architecture compatibility, including refinements for Raspberry Pi and other low-power devices through kernel 4.9 updates.[25][26] In October 2017, version 8.2 followed with further hardware improvements for Intel and Raspberry Pi platforms, addressing minor compatibility issues across a range of ARM-based systems.[27] Version 9.0 arrived in February 2019 alongside Kodi 18.0 "Leia," utilizing Linux kernel 4.19 to enhance multimedia processing and x86_64 support.[28][29] This release marked refinements in user experience, including better integration for add-ons and media library management. Version 9.2, released later in 2019 and culminating in 9.2.8 in 2020, extended these capabilities with hotfixes and updates to Kodi 18.x, maintaining kernel 4.19 while bolstering stability for ongoing ARM deployments.[30] The 10.0 series, launched in August 2021 with Kodi 19.1 "Matrix," adopted Linux kernel 5.10 to support modern hardware decoding and dropped legacy configurations incompatible with newer architectures.[31][5] Subsequent point releases like 10.0.2 in March 2022 updated Kodi to 19.4, focusing on reliability for Raspberry Pi 2/3/4 models.[32] In March 2023, version 11.0 debuted with Kodi 20.0 "Nexus" and Linux kernel 6.1, introducing NVIDIA GPU support via the open-source Nouveau driver and a new Generic-Legacy image for older x86 hardware.[33][5] This milestone emphasized broader compatibility, including initial accommodations for emerging ARM64 devices, with point releases like 11.0.3 in July 2023 refining Kodi to 20.2.[34] Version 12.0, released in May 2024, aligned with Kodi 21.0 "Omega" and Linux kernel 6.6, transitioning 64-bit ARM devices such as Raspberry Pi 4 and 5 to aarch64 architecture for enhanced performance.[35][5] This update integrated support for the Raspberry Pi 5, enabling hardware-accelerated 4K playback via the BCM2712 SoC.[36][4] In August 2025, version 12.2 advanced to kernel 6.16.x (6.12.x for Raspberry Pi devices) while updating Kodi to 21.2, and the November 2025 release of 12.2.1 incorporated Kodi 21.3 with kernel 6.16.x (6.12.x for Raspberry Pi devices), discontinuing the outdated NVIDIA 340.xx legacy driver due to compilation incompatibilities with modern kernels.[15][37][3]| Version | Release Date | Kodi Version | Linux Kernel | Key Highlights |
|---|---|---|---|---|
| 7.0 | April 2016 | 16.1 "Jarvis" | 4.x | Fork inception, basic ARM/x86 stability.[23] |
| 8.0 | February 2017 | 17.0 "Krypton" | 4.9 | Enhanced ARM support, OS refinements.[25] |
| 9.0 | February 2019 | 18.0 "Leia" | 4.19 | Improved media processing, add-on integration.[28] |
| 10.0 | August 2021 | 19.1 "Matrix" | 5.10 | Modern decoding, Raspberry Pi 4 focus.[31] |
| 11.0 | March 2023 | 20.0 "Nexus" | 6.1 | NVIDIA Nouveau, Generic-Legacy image.[33] |
| 12.0 | May 2024 | 21.0 "Omega" | 6.6 | aarch64 for ARM64, Raspberry Pi 5 integration.[38] |
| 12.2.1 | November 2025 | 21.3 "Omega" | 6.16.x (6.12.x for RPi) | NVIDIA 340.xx discontinuation, hardware bumps.[3][15] |
Features
Core components
LibreELEC is built around a customized Linux kernel, such as version 6.16.x in release 12.2.1 for generic hardware and 6.12.x for Raspberry Pi 5, incorporating patches optimized for media playback and hardware acceleration.[5][4] The system utilizes systemd as its init process for managing services and boot procedures.[40] The media stack centers on Kodi as the primary frontend, with version 21.3 included in release 12.2.1 (November 2025), providing the user interface for media management and playback.[3][5] FFmpeg handles video and audio decoding, enabling support for a wide range of formats. For audio output, the system employs ALSA as the core driver, supplemented by PulseAudio for advanced routing, such as Bluetooth device integration.[41] On non-proprietary hardware like AMD and Intel GPUs, Mesa provides open-source graphics rendering and supports features like HDR output via the GBM/V4L2 stack.[42] The filesystem structure features a read-only Squashfs root partition for the core system, ensuring stability and compactness, while the writable /storage partition uses ext4 for user data, settings, and media libraries. BusyBox supplies essential command-line utilities in a lightweight footprint suitable for embedded environments. Networking is managed by ConnMan, which handles wired, wireless, and VPN connections efficiently. Unlike full desktop distributions, LibreELEC boots directly into Kodi without a traditional graphical desktop environment. Updates are facilitated through a built-in mechanism accessible via the LibreELEC Settings add-on, allowing seamless over-the-air upgrades to new releases while preserving user configurations. Add-on support integrates with Kodi's repository system, enabling extensions for additional media services and functionalities. Security provisions include an embedded iptables-based firewall, which is disabled by default but can be enabled and configured through settings for custom rules. SSH access is available for remote management, with key-based authentication recommended over the default password to enhance protection; the system receives security patches through regular release updates.[14][43]Hardware compatibility
LibreELEC supports a range of architectures, including x86-64 for Intel and AMD PCs, as well as 32-bit and 64-bit ARM for single-board computers (SBCs) and TV boxes.[42] Official images are available for several platforms, including Raspberry Pi models 2, 3, 4, 400, and 5 (with model 5 supported from LibreELEC 12.0); Generic x86-64 for UEFI/BIOS-based PCs; Amlogic devices using SoCs such as S905, S905X/D, S912, S905X2/D2/Y2, S922X, and S905X3/D3 (with alpha support for some Gen10+ variants); Rockchip RK3288 (e.g., ASUS Tinker Board) and select newer SoCs like RK3328; Allwinner A64, H3, H5, H6, and R40; and Odroid devices such as C2 and N2 via Amlogic images. Note that Raspberry Pi 4 and 5 use 64-bit AArch64 images starting from LibreELEC 12.0.2.[12][36][44][45][46][47][48] Hardware requirements include a minimum of 512 MB RAM (though 1 GB or more is recommended for stable performance) and at least 8 GB of storage via SD card, USB drive, or SSD. Support for hardware video acceleration is provided through drivers like V4L2 for newer ARM devices and VC4 for older Raspberry Pi models, enabling efficient decoding of formats such as H.264 and HEVC on compatible hardware.[49][12][45] Limitations include the absence of support for legacy hardware, such as NVIDIA 340.xx drivers (dropped in LibreELEC 12.2) and 32-bit x86 architectures, which are not supported; Raspberry Pi 0 and 1 are unsupported, as are most Android TV boxes without custom community builds. Official support focuses on bootable media rather than internal installation for some Amlogic devices to avoid bricking risks.[15][50][45] Community-verified devices are documented on the official LibreELEC wiki, with updates for new hardware like the Raspberry Pi 5 introduced in version 12.0 and later through kernel enhancements.[12][15]Installation and usage
Installation process
The installation of LibreELEC begins with downloading the appropriate image file from the official website at libreelec.tv/downloads, where users select the version tailored to their hardware, such as the .img.gz format for Raspberry Pi devices or Generic x86_64 builds for PCs.[6] These images are provided for various platforms including single-board computers (SBCs) like Raspberry Pi and Amlogic devices, as well as x86/x64 systems. To ensure integrity, users verify the downloads using SHA256 checksums available via the mirrorlist endpoints on the releases server, such as by appending ?mirrorlist to the image URL. The recommended tool for creating bootable media is the LibreELEC USB-SD Creator application, version 1.5 as of October 2024, which supports Windows 10/11 (64-bit), macOS 14.x and later, and can be run with administrator privileges to select, download, and write images to USB drives or SD cards.[51] For Linux users, alternative methods include using the dd command or third-party tools like Balena Etcher to flash the image, as the official creator lacks native Linux support but the process remains straightforward.[52] The tool erases all data on the target drive during writing, so backups are essential; a progress bar indicates completion, after which the media is ready for booting. Installation involves direct image writing rather than a traditional OS installer, with automatic partitioning and filesystem expansion occurring on first boot. Users insert the prepared SD card or USB into the target device, ensure the BIOS/UEFI is set to boot from it (for PCs), and power on the hardware. On initial startup, LibreELEC detects the storage, resizes the partition to utilize available space, and launches a setup process that prompts for network configuration (via Ethernet or Wi-Fi), timezone selection, and the Kodi media center wizard for basic personalization.[52] This headless-capable boot allows remote access via SSH if enabled, though PXE network booting is not supported natively. Supported methods vary by hardware: for SBCs like Raspberry Pi, installation uses microSD cards formatted and flashed with the device-specific image, inserted into the card slot for booting. On x86/x64 PCs, USB drives serve as the primary media, booting directly into a live environment, with options to install to an internal SSD or HDD using the built-in installer accessed via the LibreELEC Settings add-on under System > Install to Internal, which formats the selected drive and copies the system while preserving settings.[53] BIOS adjustments are required for internal SSD booting, prioritizing the drive in the boot order. For headless setups on network-connected devices, SSH access post-boot enables configuration without a display. Common troubleshooting addresses bootloader issues, such as on Raspberry Pi where users may need to edit the config.txt file on the boot partition (e.g., to adjust HDMI output or overclocking) using a text editor on another computer before inserting the SD card.[54] For PCs, disabling Secure Boot in the BIOS/UEFI settings is often necessary, as LibreELEC's Syslinux bootloader lacks signing compatible with enabled Secure Boot, preventing boot failures on modern hardware.[55] If the system fails to boot, verifying the image checksum, ensuring compatible hardware per the supported list, and checking forum logs via SSH can resolve most issues.[56]Configuration and customization
LibreELEC provides configuration and customization options primarily through the integrated Kodi media center interface and underlying system files, allowing users to personalize the media playback experience and optimize hardware performance post-installation. In the Kodi interface, users can customize the appearance by selecting and modifying skins from the official repository, install add-ons such as audio/video decoders or encoders to extend functionality, and set up media library scraping by adding sources over network protocols like NFS, SMB, or UPnP.[57][58] System-level settings are adjusted via the LibreELEC Settings add-on within Kodi or by editing files directly; for instance, SSH access is enabled through the Services tab in the add-on, enabling remote command-line management with the default root user and 'libreelec' password.[14] Remote control pairing supports HDMI-CEC for TV remote integration, configurable in Kodi's System > Input > Peripherals menu, and IR receivers via device tree overlays in config.txt, such as dtoverlay=gpio-ir,gpio_pin=23 for GPIO-based setups.[59] Network shares are mounted persistently using systemd .mount files in /storage/.config/system.d/, specifying options like fstype=nfs or cifs for SMB to integrate remote storage into the local filesystem.[60] On Raspberry Pi hardware, overclocking is achieved by adding parameters to /flash/config.txt, such as arm_freq=1500 and over_voltage=2, followed by a reboot to apply changes.[54] Storage management involves automatic mounting of external HDDs or SSDs under /storage/media upon USB insertion, with persistent mounts configurable via fstab entries or systemd units for boot-time availability. Multi-boot configurations on PCs support integration with GRUB bootloaders by installing LibreELEC to a dedicated partition and adding a menuentry for the EFI bootloader. Backup and restore processes entail connecting a USB drive, mounting it, and copying the /storage directory contents to preserve user data, settings, and media databases.[6][9] Advanced tweaks require SSH or direct file access, as no additional GUI is provided beyond Kodi; for example, cache settings are modified in /storage/.kodi/userdata/advancedsettings.xml with entries likeDevelopment and community
Build system
The LibreELEC build system consists of a collection of Bash and Python scripts designed to automate the cross-compilation of approximately 260 to 380 interdependent open-source packages into a minimal, bootable Linux image optimized for Kodi media centers. Hosted on GitHub at the LibreELEC/LibreELEC.tv repository, it enables developers to generate custom images for various target architectures, such as x86_64 and ARM, from a host machine running a Linux distribution.[63][11] To initiate a build, developers must first clone the repository using Git and check out the desired release branch or tag, such as12.0.2 for the Omega series aligned with Kodi 21. The core command is PROJECT=Generic ARCH=x86_64 make image, which compiles the system and produces output files including a compressed disk image (.img.gz) for installation on USB or SD cards and a .tar archive for system updates, both located in the target/ subdirectory. Dependencies on the host are managed through installation scripts that use apt to fetch tools like git, make, gcc, and [rsync](/page/Rsync); in LibreELEC 10.x and later, Docker is recommended and can be installed via scripts for build isolation on Ubuntu 22.04 LTS or equivalent hosts. Minimum hardware requirements include at least 20 GB of disk space and 8 GB of RAM for reasonable build times, though performance scales with more cores and faster storage—e.g., a mid-range setup may take 3 hours, while high-end systems complete in under 30 minutes.[63][7]
Customization is achieved by modifying source code, adding new packages, or applying patches directly in the repository structure. New packages are integrated by creating a package.mk file in the appropriate packages/<system>/ or packages/<addon>/ directory, specifying variables like PKG_NAME, PKG_VERSION, PKG_URL for source downloads, and build instructions using standard GNU Make syntax; dependencies are declared via PKG_DEPENDS_TARGET to ensure proper compilation order. Kernel and driver patches are added to dedicated directories such as projects/<project>/patches/linux/ or packages/linux/patches/, allowing targeted modifications like hardware enablement without rebuilding the entire system—minor changes can recompile in 1-2 minutes. Advanced options, configurable via environment variables or a persistent ~/.libreelec/options file, include THREADCOUNT for parallel jobs (e.g., 50% to utilize half the CPU cores), DEBUG=yes for including debugging symbols (increasing image size), and BUILDER_NAME for custom metadata.[64]
For ongoing development, the build system supports automated nightly snapshots generated via GitHub Actions from the master and stable branches, providing pre-compiled images for testing at https://test.libreelec.tv/. These align with release branches like 12.0 and facilitate rapid iteration, with tools like scripts/clean for workspace management and tools/download-tool for pre-fetching sources to avoid interruptions.[65][63]