TrueNAS Early Release Documentation
This content follows TrueNAS 26 releases.
Use the Product and Version selectors above to view content specific to a stable software release.
- Documentation Hub
- /
- TrueNAS 26 (Early)
- /
- Getting Started
- /
- TrueNAS 26 Version Notes
TrueNAS 26 Version Notes
17 minute read.
Early releases are intended for testing and feedback purposes. Do not use early-release software for critical tasks.
April 7, 2026
The TrueNAS team is pleased to release TrueNAS 26-BETA.1! This first public release version of TrueNAS 26 has software component updates and new features that are in the polishing phase. See 26 Major Features for an overview of what’s new in this release.
Upgrading from TrueNAS 25.10 to 26-BETA.1 is not available in the TrueNAS UI until TrueNAS 25.10.3 is released. Users on TrueNAS 25.10 who wish to test 26-BETA.1 before that time can manually install or upgrade by downloading directly:
Special thanks to (GitHub users): Franco Castillo, AquariusStar, Rogelio Tajes Piñeiro, Aurélien Sallé, dany22m, ReiKirishima, Christos Longros, Lee Jihaeng, Aui162, Seele Volleri, Ban, Michael Rohrhirsch, PCAsusM1981, Cantabile, Fernando G. Monteiro, Joda Stößer, Marius, herbkk, saso-g1, René, Jehu Marcos Herrera Puentes, Amir Burbea, Piotr Jasiek, Eric Schultz, Kent Ross, fkwp, Gautam krishna R and Joel May for contributing to TrueNAS 26-BETA.1. Visit our guide for information on how you too can contribute.
Adds support for LXC containers in Enterprise High Availability (HA) configurations (NAS-138309). Containers can now fail over between HA controllers. HA container failover requires a static IP configuration. See Containers for configuration details.
Adds GPU passthrough support for LXC containers (NAS-138569, NAS-138570, NAS-138700). Users can assign NVIDIA and other supported GPU devices to LXC containers from the container configuration screen in the UI.
Adds Multi-Path I/O (MPIO) support for Fibre Channel connections (NAS-137252). Fibre Channel configurations can now use multiple paths for improved redundancy and throughput. This option is available in the Fibre Channel port configuration.
Adds SMB3 unix extensions support for multiprotocol shares (NAS-139988). When a share uses the Multi-Protocol purpose (for example, SMB combined with NFS or local app and container access), TrueNAS now enables SMB3 unix extensions. Linux clients with SMB3 POSIX support can use filesystem primitives not normally available through standard SMB semantics. Windows clients without unix extension support continue to behave normally.
Adds BRT (Block Reference Table) support to the
zpool prefetchcommand for faster pool import operations (NAS-139230). Pool imports on systems that use block cloning are now faster, as the prefetch operation includes BRT metadata.Adds an option to de-register a system from TrueNAS Connect (NAS-139544). Users can now remove a system’s TrueNAS Connect registration from the TrueNAS Connect configuration screen without needing to contact support.
Adds support for the
include:key in custom app Docker Compose configurations (NAS-137498). Custom app Compose files can now reference external Compose files that define services, allowing users who manage their own Docker Compose files outside TrueNAS to use modular configurations.Updates the Pools and storage screens to reflect OpenZFS 2.4 changes, including the new separation of special and dedup vdev types (NAS-138129). Pool creation and management dialogs now correctly represent the new vdev types available in OpenZFS 2.4.
Improves the Storage Dashboard to show the reason a pool is degraded (NAS-138613). Previously, a degraded pool indicator offered no detail on the cause. The dashboard now provides context so users can take corrective action.
Updates the Samba build to version 4.23 (NAS-139190). See the Samba 4.23.0 release notes for upstream changes. Note that changes to Samba defaults do not necessarily change TrueNAS defaults. See Software Component Versions for all component version updates in this release.
Improves touch and mobile usability for side panels and configuration screens (NAS-139925, NAS-139786, NAS-138896). Side panels now scroll correctly in mobile browsers, canvas edge spacing is improved for touch targets, and the Save button on the Add Rsync Task screen is no longer hidden on small screens.
Fixes TrueNAS updates failing with errors that could leave apps non-functional or set a broken boot environment as default (NAS-139794, NAS-139545). A “pool or dataset is busy” error during updates could set an incomplete boot environment as default. A separate regression also caused apps to fail to start after updating. Both issues are resolved.
Fixes the System > Services screen showing as empty (NAS-139571). A regression could cause the services list to appear blank on affected systems, preventing users from starting, stopping, or configuring services from the UI.
Fixes an issue where datasets could not be loaded in the UI (NAS-140389). A middleware issue could prevent dataset information from loading on the Datasets screen, showing an error instead of the dataset tree.
Fixes available space calculations for pools with special or dedup vdevs (NAS-139820). Incorrect accounting could cause available space to display inaccurate values on pools using special allocation or dedup vdevs.
Fixes an issue where virtual DRAID devices appeared as physical disks in the disk inventory (NAS-140344). On pools using DRAID vdevs, virtual devices could be incorrectly counted alongside physical drives, causing inaccurate disk inventory results.
Fixes datasets becoming unavailable after a ZFS send replication operation (NAS-139363). A ZFS issue could cause target datasets to enter an unavailable state after a send operation completed. Datasets are now accessible immediately after replication finishes.
Fixes a boot delay of up to 120 seconds on systems with VLAN interfaces configured for DHCP (NAS-139038). Systems using VLAN interfaces with DHCP experienced long waits during boot due to a
dhcpcdconfiguration issue. Boot now completes without the delay.Fixes an error that prevented setting secondary IP address aliases on network interfaces (NAS-139803). A
KeyError: 'alias_interface_id'error could occur when saving secondary aliases in the network interface configuration.Fixes the Samba Spotlight metadata service connection so that macOS Spotlight search works correctly on SMB shares (NAS-137715). The Spotlight AF_UNIX socket connection was established as a non-privileged user, causing authentication failures. The connection now runs with the correct permissions.
Fixes an error that prevented editing share ACLs (NAS-139535). Users attempting to modify permissions on SMB or NFS shares through the ACL editor could receive errors and be unable to save changes.
Fixes NFS shares showing no available actions in the Shares screen (NAS-139490). The action buttons for NFS shares could fail to render correctly, preventing users from editing or deleting NFS shares from the UI.
Fixes an error that prevented updating an iSCSI auth method when Mutual CHAP was selected (NAS-139397). Users could not save changes to iSCSI authorized access entries with Mutual CHAP configured.
Fixes USB and PCIe device passthrough to virtual machines (NAS-139045, NAS-139356). A regression in an earlier nightly build broke the ability to pass USB and PCIe devices through to VMs. Both USB and PCIe passthrough are restored in BETA.1.
Fixes Rsync task setup failures related to remote path validation and host key verification (NAS-139773). Remote path validation could incorrectly reject valid paths, and host key verification could fail even after accepting the key. Both issues are resolved.
Fixes SNMP alerts that stopped sending notifications (NAS-140259). A regression could cause SNMP alert notifications to fail silently on affected systems. SNMP monitoring integrations relying on TrueNAS alerts now receive notifications correctly.
Fixes the CPU reporting chart to show both per-core and total CPU usage (NAS-135633). The Reporting screen previously only showed aggregated CPU usage. Users can now view individual core utilization alongside the total.
Fixes UI regressions introduced by an Angular framework upgrade, including session logouts on page refresh in Firefox and broken tooltips across multiple screens (NAS-139491, NAS-139342). Firefox users were logged out unexpectedly on page refresh, and tooltips and contextual popovers stopped working throughout the interface. Both issues are resolved.
Fixes the TrueNAS web UI preventing NVIDIA driver removal when the GPU has already been uninstalled (NAS-137282). When an NVIDIA GPU was physically removed, the UI did not allow removing the associated driver package. The driver can now be removed independently of hardware presence.
Click here to see the full 26 changelog or visit the TrueNAS 26-BETA.1 Changelog in Jira.
These are ongoing issues that can affect multiple versions in the 26 series.
When resolved, issues move to Notable Changes for the appropriate release.
See the latest status on Jira for public issues discovered in 26-BETA.1 that are being resolved in a future TrueNAS release.
See the Release Notes section of the TrueNAS forum for ongoing updates about known issues, investigations, and statistics about TrueNAS releases.
TrueNAS 26 brings many new features and improvements to the TrueNAS experience.
TrueNAS 26 introduces an annual release cadence with simplified version numbering. Instead of fish-themed code names and multi-digit version strings, releases now use straightforward numbers like “26.1”. TrueNAS 26 receives feature packs, security updates, and hotfixes throughout the year, providing more predictable upgrade cycles and extended testing periods for both the engineering team and end users.
WebShare provides browser-based file access without requiring SMB or NFS client mounting on user systems. Users can browse, upload, download, and manage files directly from a web browser, with support for folder creation, filtering, snapshot timeline viewing, shareable links, and hidden file toggling. WebShare is configured through TrueNAS Connect and requires a dataset and at least one local user account with WebShare access enabled.
When TrueSearch is enabled in the WebShare service configuration, all active shares are indexed for fast file searching by filename, content, or file type. Encrypted datasets are excluded from indexing. Passkey authentication options provide flexible access control for WebShare users.
TrueNAS Ransomware Defense is a security service that monitors SMB and NFS file shares in real time and automatically responds to ransomware attacks to protect data stored on the TrueNAS system. The service is available through TrueNAS Connect and uses multiple detection methods, including honeypot decoy files, suspicious behavior analysis, encryption signature identification, and snapshot comparison to track unusual data changes. When a threat is detected, configurable protection responses can automatically disable affected shares, set them to read-only, restrict access, or pause snapshot deletion to preserve recovery points. IP blocking, threat scoring, and snapshot-based recovery tools are available to investigate incidents, remediate threats, and restore data.
Containers, introduced as an experimental feature in TrueNAS 25.04, are fully supported in TrueNAS 26. Containers provide lightweight, isolated Linux environments that share the host kernel while maintaining their own file system, processes, and network configuration, using fewer system resources than virtual machines while starting quickly and scaling efficiently.
TrueNAS 26 extends container support to Enterprise systems with High Availability (HA) configurations, enabling container failover between controllers. HA container failover requires a static IP configuration.
Users migrating from TrueNAS CORE who previously relied on custom Jails can use containers as a supported migration path. See Containers for configuration details.
TrueNAS 26 introduces stateful SMB HA failover for Enterprise systems with High Availability (HA) configurations. When enabled in the SMB service configuration, TrueNAS maintains SMB session state across controller failover events, allowing SMB clients to recover existing connections without re-authentication after a failover. See Enabling SMB Stateful Failover for configuration details.
TrueNAS 26 adds Spotlight search support for SMB shares, allowing macOS clients to use Spotlight to search file contents directly on TrueNAS SMB shares. Spotlight search is enabled per share in the SMB service configuration.
TrueNAS 26 integrates OpenZFS 2.4, which introduces new capabilities including hybrid pool support for combining flash and HDD storage, physical block rewriting, and dynamic gang header improvements. See OpenZFS Feature Flags for details on newly added feature flags.
TrueNAS 26 ships with Linux Kernel 6.18 LTS, enabling support for new hardware and receiving long-term maintenance and security updates from the upstream kernel project.
This section tracks features removed in 26 and features deprecated in 26 for future removal. Plan migrations immediately to avoid disruptions during upgrades.
Deprecated: 25.04
Removed: 26
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.
The TrueNAS REST API has been fully replaced by the versioned JSON-RPC 2.0 Websocket API.
Migration Path:
- Review current API integrations and identify all REST API calls.
- Review the Websocket API documentation to identify replacement endpoints.
- Update all scripts and integrations to use Websocket API endpoints.
- Test thoroughly in a non-production environment.
- Deploy updated integrations before upgrading to 26.
Impact: Systems still using the REST API must migrate to the Websocket API before upgrading to 26. REST API endpoints do not function in 26 and later.
See Also:
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.
Upgrading from TrueNAS 25.10 to 26-BETA.1 is not available in the TrueNAS UI until TrueNAS 25.10.3 is released. Users on TrueNAS 25.10 who wish to test 26-BETA.1 before that time can manually install or upgrade by downloading directly:
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 26 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.2.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.3.3) are listed below:
| Feature Flag | GUID | Notes |
|---|---|---|
block_cloning_endian | com.truenas:block_cloning_endian | Corrects ZAP entry endianness issues in the Block Reference Table (BRT) used by block cloning. Read-only compatible. |
dynamic_gang_header | com.klarasystems:dynamic_gang_header | Enables larger gang headers based on pool sector size. Not read-only compatible; must be manually enabled. |
physical_rewrite | com.truenas:physical_rewrite | Enables physical block rewriting that preserves logical birth times, reducing incremental send stream sizes. Read-only compatible. |
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).