Creating isolated userland Python virtualenvs in TrueNAS

Creating isolated Python environments to do console monitoring in TrueNAS.

Creating isolated userland Python virtualenvs in TrueNAS
Photo by regularguy.eth / Unsplash

The problem

I needed to do console monitor of a TrueNAS server using bpytop (, a text based, Python resource monitor.

In order to create immutable and predictable deployments, TrueNAS disables installation of Debian packages. If you want to install a Python virtualenv in TrueNAS, you'll quickly notice that the python3-venv package is not installed by default. This makes it impossible to create isolated Python virtual environments, even userland Python virtual environments.

If you try to create a Python virtualenv in TrueNAS, you will get the following error message.

$ python3 -m venv venv

The virtual environment was not created successfully because ensurepip is not
available.  On Debian/Ubuntu systems, you need to install the python3-venv
package using the following command.

    apt-get install python3-venv

You may need to use sudo with that command.  After installing the python3-venv
package, recreate your virtual environment.

Failing command: ['/mnt/personal/ds-home/console/venv/bin/python3', '-Im', 'ensurepip', '--upgrade', '--default-pip']

However as mentioned above, package installation is disabled and running the command sudo apt-get install python3-venv results in the protection error zsh: permission denied: apt-get.


While the command python3 -m venv venv fails, it does manages to create the basic virtualenv folder structure and also installs a Python binary.

Virtualenvs can be used in two ways: persistent or one-off. The virtualenv create in TrueNAS cannot be used in a persistent way because it is missing the activate script. However, calling the Python binary in the virtualenv is enough to execute code in an isolate manner.

The next step is to enable installation of Python packages. Since pip is not available it is necessary to bootstrap it. This can be done downloading an executable and packaged version of pip.

wget -c

Using the packaged version of pip (pip.pyz), it is possible to install the proper pip package inside the virtualenv.

./venv/bin/python3 ./pip.pyz install pip

With pip installed the virtualenv is for all intended purposes feature complete and complex packages can now be easily installed.

venv/bin/pip3 install bpytop

To execute the installed package, the complete path to the binary inside the virtualenv must be used.


Console monitoring of a TrueNAS server is now possible without installing system wide operating system packages or Python libraries. All Python code resides in an isolate virtualenv in the user's home folder.