TrueNAS Stable Version Documentation
This content follows TrueNAS 25.04 (Fangtooth) releases.
Use the Product and Version selectors above to view content specific to a different software release.
25.04 (Fangtooth) Version Notes
23 minute read.
25.04 Fangtooth
TrueNAS 25.04 (Fangtooth) brings many new features and improvements to the TrueNAS experience:
NFS over RDMA support (Enterprise Feature - see Configuring the NFS Service)
Fibre Channel support (Enterprise Feature)
iSCSI XCOPY support through ZVOL block cloning (NAS-130017).
Versioned TrueNAS JSON-RPC 2.0 over WebSocket API with new and improved API documentation (see API Reference)
User-linked API Keys (see Managing API Keys)
Improved UI Login Experience (NAS-130810)
Improved STIG Compliance and Security Focus (Enterprise Feature - NAS-127235)
Enable support for ZFS Fast Deduplication (NAS-127088)
New experimental Instances (formerly Virtualization) features.
TrueNAS 25.04 replaces the previous KVM hypervisor (TrueNAS 24.10 and earlier) with Incus for virtual machine (VM) deployment. It also introduces support for Linux system containers (LXC), enabling lightweight isolation similar to jails in TrueNAS CORE.
Instances are an experimental feature intended for community testing only. Users with production VMs on TrueNAS 24.10 should not upgrade to TrueNAS 25.04 until after this experimental feature stabilizes in a future TrueNAS release.
See Migrating Virtual Machines for more information.
Improvements to the TrueNAS apps service, including per-app selection of IP addresses (See TrueNAS Apps in the Upgrade Notes).
For adventurous users who want to experiment with the latest feature development, 25.04 (Fangtooth) nightly images are available from the TrueNAS downloads server.
More details are available from Software Releases.
The release names and dates provided here are tentative and can change at any time.
| 
Previous
Current
Next
TrueNAS 25.10 - Goldeye
Latest:Anticipated:
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:
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 SMB share failures after an upgrade.
- 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.
- The TrueNAS REST API is deprecated in TrueNAS 25.04. Full removal of the REST API is planned for a future release.
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.
25.04 also introduces user-linked API access keys, allowing administrators to configure per-user access to the TrueNAS API. Keys are revocable and can be configured to automatically expire on a preset date.
Active Directory/LDAP user-linked API key support is available to TrueNAS Enterprise customers only.User-linked API keys allow for better integration of TrueNAS into third-party solutions. Use this as a reference for projects that require direct TrueNAS integration.
Always back up and secure keys. TrueNAS displays the key string only once, in the API Key confirmation dialog, immediately after creation.
User-linked API keys allow password-equivalent access to the TrueNAS middleware. API keys are not subject to the two-factor authentication (2FA) configuration of the associated user account. A compromised API key results in access to the TrueNAS API as the associated user, even if the account is configured to require 2FA.
For increased security, HTTPS with SSL/TLS transport security is required for TrueNAS API authentication using API keys. TrueNAS automatically revokes any user-linked API keys passed as part of an authentication attempt via insecure (HTTP) transport. A revoked API key cannot be used until it is reset. Resetting generates a new key-string. Remember to update clients to use the new key.
See Managing API Keys for more information.
Legacy API keys created in TrueNAS 24.10 or earlier migrate to the root, admin, or truenas_admin account, depending on server configuration.
Existing API keys created via the TrueNAS API (not UI or TrueCommand) that specify an allow list with white-listed API methods are revoked upon upgrade because there is no clean way to migrate to the new system. Administrators should create a service account (a user account for this particular purpose), define desired access rights for this service account, generate a new user-linked API key, and distribute it to the API client.
In TrueNAS 25.04 (and later), users must log in as a system administrator with full administrative access to upload or download a system configuration file. Other users, including restricted admin accounts such as a shares administrator, cannot perform database operations. See Using Administrator Logins for more information on admin account types.
The built-in Netdata UI, accessible from the Netdata button on the Reporting screen in TrueNAS 24.04 and 24.10, is removed in TrueNAS 25.04 (and later) for security hardening. Users wishing to continue using the Netdata UI to monitor system reports can install the Netdata application.
To prevent unexpected failures in SMB shares, TrueNAS automatically disables SMB2/3 lease support and AAPL extensions (typically used to configure Time Machine) globally when multiprotocol SMB/NFS shares are enabled (NAS-133680).
This means that in TrueNAS 25.04 and later, multiprotocol shares are incompatible with Time Machine shares on the same system. To prevent service interruption, Time Machine users should make sure that no multiprotocol shares are configured on TrueNAS.
TrueNAS 25.04 replaces the previous KVM hypervisor (TrueNAS 24.10 and earlier) with Incus for virtual machine (VM) deployment. It also introduces support for Linux system containers (LXC), enabling lightweight isolation similar to jails in TrueNAS CORE.
Manual Migration RequiredDue to configuration incompatibilities between the previous KVM hypervisor (TrueNAS 24.10 and earlier) and Incus in TrueNAS 25.04, existing VM configurations do not transfer automatically during the upgrade. However, TrueNAS retains storage zvols, allowing you to manually recreate the previous VM configurations and get them back online.
Instances are an experimental feature intended for community testing only. Users with production VMs on TrueNAS 24.10 should not upgrade to TrueNAS 25.04 until after this experimental feature stabilizes in a future TrueNAS release.
Application maintenance, including version updates, features, and configuration options, is independent from TrueNAS version release cycles.
See the TrueNAS Apps documentation and the truenas/apps repository for more information.
TrueNAS Apps Support Timeline for 24.04 and 24.10Summary: Applications added to the TrueNAS Apps catalog before December 24, 2024, require updates to enable host IP port binding. These updates roll out on June 1, 2025.
Due to breaking changes involved in enabling host IP port binding, June 1, 2025 is the deadline for automatic apps migration from 24.04 to 24.10 on upgrade. Migrate from 24.04 to 24.10 before June 1, 2025, to ensure automatic app migration.
Additionally, existing applications installed on 24.10 do not automatically update after June 1, 2025. Upgrade to 25.04 before June 1 to continue receiving regular app updates. Users who do not wish to upgrade to 25.04 before June 1 must manually uninstall and redeploy affected applications after that date to resume app updates.
Timeframe App Migration
24.04 → 24.10App Updates in 24.10 App Migration
24.10 → 25.04App Updates in 25.04 Before June 1, 2025 ✅ Supported ✅ Supported ✅ Supported ✅ Supported After June 1, 2025 ❌ Not Supported ⚠️ Action required ✅ Supported ✅ Supported
With a stable release, upgrading to TrueNAS 25.04 (Fangtooth) from an earlier TrueNAS release is primarily done using the web interface update process. Another upgrade option is to use a TrueNAS .iso file to perform a fresh install on the system and then restore a system configuration file.
The chart below shows recommended paths for upgrading from earlier TrueNAS versions.
Update the system to the latest maintenance release of the installed major version before attempting to upgrade to a new major version.
Permitted upgrade methods are:
- update: apply an automatic update using the Update screen in the TrueNAS UI or install a manual update file. Some upgrade paths do not support these options (see chart).
- ISO install: save a current TrueNAS configuration file, perform a fresh install using an
.iso file for the target version, and then upload the previously saved configuration.
Users can skip major versions with a fresh ISO install followed by a configuration file upload. Carefully review release notes for each skipped major version before upgrading, noting any service deprecations or significant changes that impact the previous configuration. Consider stopping at major versions with significant impacts to address changes before continuing the upgrade path or be prepared to manually reconfigure incompatibilities on the latest target version.
This chart shows the basic update path to and from the latest release of each TrueNAS major version. Depending on your use case and risk tolerance, some users may prefer to remain on an earlier minor or major version for a period of time before updating. Visit the TrueNAS Software Status page for recommendations on which software version to use, tailored to user types ranging 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.4
13.3-U1"]
C -->|ISO install| H
C -->|ISO install| I
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.1 (Electric Eel)"] -->|update| I
I["25.04.0 (Fangtooth)"]
flowchart LR
A["11.3-U5"] -->|update| B
B["12.0-U8.1"] -->|update| C
C["13.0-U6.4"] -->|ISO install| F
C["13.0-U6.4"] -->|"(anticipated)"| G
D["23.10.2 (Cobia)"] -->|update| E
E["24.04.2.5 (Dragonfish)"] -->|update| F
F["24.10.2.1 (Electric Eel)"] -->|"(anticipated)"| G
G["25.04 (Fangtooth)"]
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 13.0 release version (or 13.3 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
Click the component version number to see release notes for that component.
| 25.04.0 | 25.04-RC.1 | 25.04-BETA.1 | |
|---|---|---|---|
| Linux Kernel | 6.12.15 | 6.12.15 | 6.12.9 |
| OpenZFS | 2.3.0-1 | 2.3.0-1 | 2.3.0-1 |
| Docker Engine | 27.5.0 | 27.5.0 | 27.5.0 |
| NVIDIA Driver | 550.142 | 550.142 | 550.142 |
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.2.99) are listed below:
| Feature Flag | GUID | Notes |
|---|---|---|
| fast deduplication | com.klarasystems:fast_dedup | This flag is present in 24.10, but is now generally available through the TrueNAS UI. |
For more details on feature flags, see OpenZFS Feature Flags and OpenZFS zpool-feature.7.
April 15, 2025
The TrueNAS team is pleased to release TrueNAS 25.04.0! This is the first stable release of TrueNAS SCALE 25.04 (Fangtooth). It includes numerous software component updates and polished features, as well as fixes for issues discovered in 25.04-RC.1.
Special thanks to (Github users): Gleb Chesnokov and Franco Castillo for contributing to TrueNAS 25.04.0. For information on how you can contribute, visit https://www.truenas.com/docs/contributing/.
TrueNAS 25.04 (Fangtooth) brings many new features and improvements to the TrueNAS experience:
NFS over RDMA support (Enterprise Feature - see Configuring the NFS Service)
Fibre Channel support (Enterprise Feature)
iSCSI XCOPY support through ZVOL block cloning (NAS-130017).
Versioned TrueNAS JSON-RPC 2.0 over WebSocket API with new and improved API documentation (see API Reference)
User-linked API Keys (see Managing API Keys)
Improved UI Login Experience (NAS-130810)
Improved STIG Compliance and Security Focus (Enterprise Feature - NAS-127235)
Enable support for ZFS Fast Deduplication (NAS-127088)
New experimental Instances (formerly Virtualization) features.
TrueNAS 25.04 replaces the previous KVM hypervisor (TrueNAS 24.10 and earlier) with Incus for virtual machine (VM) deployment. It also introduces support for Linux system containers (LXC), enabling lightweight isolation similar to jails in TrueNAS CORE.
Instances are an experimental feature intended for community testing only. Users with production VMs on TrueNAS 24.10 should not upgrade to TrueNAS 25.04 until after this experimental feature stabilizes in a future TrueNAS release.
See Migrating Virtual Machines for more information.
Improvements to the TrueNAS apps service, including per-app selection of IP addresses (See TrueNAS Apps in the Upgrade Notes).
Notable changes since 25.04-RC.1:
- Prevent cloned blocks remapping after device removal to avoid data corruption (NAS-133555).
- Numerous improvements and bug fixes to the experimental Instances feature, including:
- Allow configuration of IO bus for disk devices in Instances (NAS-134250). This enables users to create virtualized disks using a standard other than VirtIO in cases where the OS image does not by default include VirtIO drivers.
- Improved upload speed for volume imports (NAS-134552).
- New IO Bus configuration options for Virtual Machines (NAS-134393).
- New IDMAP options for users and groups in Linux containers (NAS-134447).
- Fixed bug to allow console access for VMs created with an iso file (NAS-134253).
- Fix KeyError crash in ipmi.lan.query (NAS-134736).
- Fix permissions for user app config file (NAS-134558).
- Prevent upgrade failure if encrypted fields are not readable in the DNS auth table (NAS-134728).
- Optimize Dashboard resource widgets and fetch metrics once per page load (NAS-132124).
Click here for the full changelog of completed tickets that are included in the 25.04.0 release.
To switch between detail and list views for the changelog, press t.
Open the changelog in Jira to see the Export menu to print or download the changelog in various file formats.
The SSH service does not start if certain user-provided SSH auxiliary parameters are configured (NAS-135367). This is known to affect
matchparameters minimally, but might impact other parameters as well.A validation check intended to prevent users from creating multiple VMs from the same zvol source has the unintended consequence of preventing attaching the same virtual disk to multiple Instance containers (NAS-135371).
Some users of TrueNAS Apps attempting to configure GPU allocation report the error
Expected [uuid] to be set for GPU inslot [<some pci slot>] in [nvidia_gpu_selection])(see (NAS-134152).Users experiencing this error should follow the steps below for a one-time fix that should not need to be repeated.
Connect to a shell session and retrieve the UUID for each GPU with the command
midclt call app.gpu_choices | jq.For each application that experiences the error, run
midclt call -j app.update APP_NAME '{"values": {"resources": {"gpus": {"use_all_gpus": false, "nvidia_gpu_selection": {"PCI_SLOT": {"use_gpu": true, "uuid": "GPU_UUID"}}}}}}'Where:APP_NAMEis the name you entered in the application, for example, “plex”.PCI_SLOTis the PCI slot identified in the error, for example “0000:2d:00.0”.GPU_UUIDis the UUID matching the PCI slot that you retrieved with the above command.
Custom applications with TTY enabled do not display logs in the TrueNAS UI. This is due to an upstream bug, see https://github.com/docker/docker-py/issues/1394. Users experiencing this issue can resolve it by either disabling TTY or using
docker logsfrom the command line.
Click here to see the latest information about public issues discovered in 25.04.0 that are being resolved in a future TrueNAS release.