Developer Mode (Unsupported)

Developer mode is for developers only. Users that enable this functionality will not receive support on any issues submitted to iXsystems.

Only enable when you are comfortable with debugging and resolving all issues encountered on the system. Never enable it on a system that has production storage and workloads.

TrueNAS is an Open Source Storage appliance, not a standard Linux operating system (OS) that allows customization of the OS environment. By default, the root/boot filesystem and tools such as apt are disabled to prevent accidental misconfiguration that renders the system inoperable or puts stored data at risk.

However, as an open-source appliance, there are circumstances in which software developers want to create a development environment to install new packages and do engineering or test work before creating patches to the TrueNAS project.

Do not make system changes using the TrueNAS UI web shell. Using package management tools in the web shell can result in middleware changes that render the system inaccessible.

Connect to the system using SSH or a physically connected monitor and keyboard before enabling or using developer mode.

To enable developer mode, log into the system as the root account and access the Linux shell. Run the install-dev-tools command.

Running install-dev-tools removes the default TrueNAS read-only protections and installs a variety of tools needed for development environments on TrueNAS. These changes do not persist across updates and install-dev-tools must be re-run after every system update.

install-dev-tools is a developer-focused option that might not work in scenarios beyond those intended by TrueNAS developers, such as modified installations or deployments that use non-default settings.

Users with NVIDIA GPU drivers installed cannot enable developer mode while the NVIDIA kernel module is mounted. Running install-dev-tools in this state results in the following error:

/usr is currently provided by a readonly systemd system extension.
This may occur if nvidia module support is enabled. System extensions
must be disabled prior to disabling rootfs protection.

This happens because the NVIDIA drivers are overlaid onto /usr via systemd-sysext, making it read-only by design. To resolve the issue, unmerge systemd-sysext, run install-dev-tools, then merge system extensions again.