TrueNAS Development Documentation
This content follows experimental development changes in TrueNAS 27, a future version of TrueNAS.
Use the Product and Version selectors above to view content specific to a stable software release.
- Documentation Hub
- /
- TrueNAS 27 (Early)
- /
- Getting Started
- /
- TrueNAS 27 Development Notes
TrueNAS 27 Development Notes
8 minute read.
This page tracks the latest development roadmap and notes for TrueNAS 27, the next major version of TrueNAS. Nightly builds are early-stage development software intended for testing and feedback — not production use. See the Software Development Life Cycle for an overview of TrueNAS release stages and versioning.
See the stable 25.10 (Goldeye) or pre-release TrueNAS 26 release notes for information relating to those versions.
Early releases are intended for testing and feedback purposes. Do not use early-release software for critical tasks.
TrueNAS 27 is currently in active development.
Check back for more information.
These are ongoing issues that can affect multiple versions in the 27 series.
When resolved, issues move to Notable Changes for the appropriate release.
No known issues currently reported for 27 development builds.
Check back for more information.
See the Release Notes section of the TrueNAS forum for ongoing updates about known issues, investigations, and statistics about TrueNAS releases.
TrueNAS 27 is currently in active development to bring many new features and improvements to the TrueNAS experience.
Check back for more information.
This section tracks features removed in 27 and features deprecated in 27 for future removal. Plan migrations immediately to avoid disruptions during upgrades.
No features are currently removed in this version.
No features are currently deprecated for future removal.
For additional resources, see the Feature Deprecations page.
Early releases of a major version are intended for testing and feedback purposes only. Do not use early release software for critical tasks.
TrueNAS is an appliance built from specific Linux packages. Updating TrueNAS using
aptor any method other than the TrueNAS web interface can make the system inoperable.Modifying the base OS can cause unexpected behavior during upgrades:
Users who manually installed Docker on TrueNAS 24.04 or earlier can experience TrueNAS Apps failure in 24.10 or later.
This occurs due to conflicts between the manually installed and native Docker configurations.
- Affected systems can encounter
app_lifecycle.compose_actionerrors, such as:'group_add[0]' expected type 'string', got unconvertible type 'int', value: '568' - See NAS-134660 for details and a workaround.
- Affected systems can encounter
All auxiliary parameters can experience changes between TrueNAS major versions due to security and development changes. We recommend removing all auxiliary parameters from TrueNAS configurations before upgrading as these settings can result in unexpected behavior such as SMB share failures after an upgrade.
SSH auxiliary parameters are unsupported. Certain configurations can prevent the SSH service from starting.
After updating, clear the browser cache (CTRL+F5) before logging in to TrueNAS. This ensures stale data doesn’t interfere with loading the TrueNAS UI.
Application maintenance, including version updates, features, and configuration options, is independent from TrueNAS version release cycles.
See documentation and resources at the TrueNAS Apps Market and the truenas/apps repository issues tracker for more information.
- The TrueNAS REST API was deprecated in TrueNAS 25.04 and is removed in TrueNAS 26. Systems still using the REST API must migrate to the WebSocket API before upgrading.
TrueNAS (25.04 and later) uses a versioned JSON-RPC 2.0 over WebSocket API. API versions are numbered in conjunction with TrueNAS version releases.
The API documentation provides information about supported API methods and events. Documentation is included for all API versions supported by the current TrueNAS release and defaults to the latest supported API. Use the dropdown to view documentation for different supported API versions.
Advanced users can interact with the TrueNAS API to perform management tasks using the TrueNAS API Client as an alternative to the TrueNAS web UI. This websocket client provides the command line tool
midcltand allows users to communicate with middleware using Python by making API calls. The client can connect to the local TrueNAS instance or to a specified remote socket.You can access TrueNAS API documentation in the web interface by clicking laptop My API Keys on the top right toolbar account_circle user settings dropdown menu to open the User API Keys screen. Click API Docs to view API documentation.
LXC containers, introduced as an experimental feature in earlier TrueNAS releases, are fully supported in TrueNAS 26. No configuration migration is required for containers created in prior releases.
TrueNAS 26 adds the following container improvements:
- Enterprise HA support — Containers can now fail over between HA controllers (NAS-138309). HA container failover requires a static IP configuration. Containers using DHCP do not fail over.
- GPU passthrough — NVIDIA and other supported GPU devices can now be assigned to LXC containers from the container configuration screen (NAS-138569, NAS-138570, NAS-138700).
- USB and PCIe passthrough fixes — A regression that prevented USB and PCIe device passthrough to containers and VMs is resolved in BETA.1 (NAS-139045, NAS-139356).
See Containers for configuration details.
TrueNAS monitors the condition of installed HDD and SSD drives (SAS, SATA, and NVMe) through three integrated layers:
- ZFS detects sudden failures in real time during active read and write operations and marks affected vdevs or disks as faulted immediately.
- TrueNAS Middleware polls SMART data from every drive every 90 minutes. When a polled attribute crosses a failure threshold, TrueNAS generates an alert.
- Alert logic filters incoming SMART and ZFS data to suppress known-benign attribute fluctuations, reducing false-positive alerts by approximately 50% compared to prior releases.
Drive health status is visible on the Disk Health card on the Storage dashboard. Active alerts appear in the Alerts panel with details on the affected disk and recommended next steps.
Community Edition users can supplement automated monitoring with manual SMART tests run via cron jobs or the smartctl command-line tool. Third-party tools such as Scrutiny are also available from the TrueNAS Apps catalog.
See Drive Health Management for full details.
Application maintenance, including version updates, features, and configuration options, is independent from TrueNAS version release cycles.
See documentation and resources at the TrueNAS Apps Market and the truenas/apps repository issues tracker for more information.
Early releases of a major version are intended for testing and feedback purposes only. Do not use early release software for critical tasks.
Upgrading to TrueNAS 27 from an earlier TrueNAS release is primarily done using the web interface update process.
Another upgrade option is to use a TrueNAS
Update to the latest maintenance release of the current major version before upgrading to the next major version. You can then upgrade directly from the latest maintenance release to the latest release of the next major version.
This chart shows the basic upgrade paths between TrueNAS major versions. Depending on your use case and risk tolerance, you might prefer to delay upgrading to allow additional time for testing and stability. See the TrueNAS Software Status for version recommendations tailored to different user types from Developer to Mission Critical.
flowchart LR
A["11.3-U5"] -->|update| B["12.0-U8.1"]
B -->|"update / ISO install"| C["13.0-U6.8 / 13.3-U2"]
C -->|update| G
C -->|ISO install| J
D["22.02.4 (Angelfish)"] -->|update| E
E["22.12.4.2 (Bluefin)"] -->|update| F
F["23.10.2 (Cobia)"] -->|update| G
G["24.04.2.5 (Dragonfish)"] -->|update| H
H["24.10.2.4 (Electric Eel)"] -->|update| I
I["25.04.2.6 (Fangtooth)"] -->|update| J
J["25.10.2.1 (Goldeye)"] -->|"anticipated"| K
K["TrueNAS 26.0"]
flowchart LR
A["11.3-U5"] -->|update| B
B["12.0-U8.1"] -->|update| C
C["13.0-U6.8"] -->|ISO install| H
C -->|update| E
D["23.10.2 (Cobia)"] -->|update| E
E["24.04.2.5 (Dragonfish)"] -->|update| F
F["24.10.2.4 (Electric Eel)"] -->|update| G
G["25.04.2.6 (Fangtooth)"] -->|update| H
H["25.10.1 (Goldeye)"] -->|"anticipated"| I
I["TrueNAS 26.0"]
Permitted upgrade methods are:
- update: Apply updates using the Update screen in the TrueNAS UI or install a manual update file. Not all upgrade paths support automatic updates (see chart).
- ISO install: Save your TrueNAS configuration file, perform a fresh install using an
.iso file for the target version, then upload the saved configuration.
You can skip major versions using a fresh installation with configuration file restore. Before skipping versions, review release notes for each major version to identify service deprecations or significant changes that might affect your configuration. Consider upgrading incrementally through major versions with significant changes, or be prepared to manually reconfigure any incompatibilities after upgrading directly to the target version.
Migrating TrueNAS from FreeBSD- to Linux-based versions is a one-way operation. Attempting to activate or roll back to a FreeBSD-based TrueNAS boot environment can break the system.
Upgrade your FreeBSD-based TrueNAS system to the latest publicly-available release version, 13.0-U6.7 (or 13.3-U1.2 for community users), before attempting to migrate. See Software Releases for current recommended update paths to make sure you download and migrate to the correct version.
Depending on the specific system configuration, migrating from a FreeBSD-based TrueNAS version can be a straightforward or complicated process. See the Migration articles for cautions and notes about differences between each software and the migration process.
TrueNAS Enterprise customers with High Availability (HA) or Non-HA TrueNAS Hardware should consult with TrueNAS Enterprise Support for assistance before attempting to migrate.
Customers who purchase TrueNAS hardware or that want additional support must have a support contract to use TrueNAS Support Services. The TrueNAS Community forums provides free support for users without a TrueNAS Support contract.
TrueNAS Customer Support Support Portal https://support.ixsystems.com support@ixsystems.com Telephone and Other Resources https://www.ixsystems.com/support/
Click the component version number to see release notes for that component.
*TrueNAS (25.10 and later) includes the NVIDIA open GPU kernel module drivers. These drivers work with Turing and later GPUs. Earlier architectures (Pascal, Maxwell, Volta) are not compatible. See NVIDIA GPU Support for more information.
TrueNAS integrates many features provided by the upstream OpenZFS project. Any new feature flags introduced since the previous OpenZFS version that was integrated into TrueNAS (OpenZFS 2.4.1) are listed below:
For more details on feature flags, see OpenZFS Feature Flags and OpenZFS zpool-feature.7.
Have more questions?
For further discussion or assistance, see these resources:
- TrueNAS Community Forum
- TrueNAS Community Discord
- TrueNAS Enterprise Support (requires paid support contract)
Found content that needs an update? You can suggest content changes directly! To request changes to this content, click the Feedback button located on the middle-right side of the page (might require disabling ad blocking plugins).