3DF Zephyr on any Linux distro

3_df_zephyr_linux_setup

Running 3Df Zephyr on Linux (Tested on 3Df Zephyr and 3DF Zphyr Lite 8.013)

This guide covers the steps to run 3DF Zephyr on Linux using Bottles and Wine, with CUDA acceleration via native NVIDIA drivers.
If you have the full version of 3DF Zephyr you should also have acces to Scarlet. This guide also makes GPU acceleration work for Scarlet.
However I will not go over setting up compatibility of laser and lidar scanners as it is out of scope for this guide.

I have tested 3DF Zephyr, Scarlet and 3DF Zephyr Lite extensively. Everysingle feature works without a problem as if you run it on native Windows.
Plugins still need testing. But they have been notorious to get running, if at all.

Tested on Manjaro (Arch-based), but it should work on other distributions with up-to-date libraries.

Terminal: Everything in code/command blocks is executed in the terminal.

🔧 Prerequisites

✅ Optional but Recommended

Before modifying drivers or installing system components:

  • Make sure your system and libraries are up to date.
  • Create a system snapshot with Timeshift or similar in case things go wrong (e.g., system fails to boot).

✅ Sanity Check: NVIDIA & CUDA

Open a terminal and run:

nvidia-smi         # Should show your GPU and driver version
nvcc --version     # Should show the installed CUDA version

If these do not return valid results:

  • Install the latest NVIDIA driver for your distribution.
  • Install CUDA toolkit:
    • Ubuntu: sudo apt install nvidia-cuda-toolkit
    • Manjaro: pamac install cuda-tools
    • Arch: cuda-tools are available in the AUR. You can use yay to install them yay cuda-tools

Reboot your system after installation or updates.

Only proceed if both nvidia-smi and nvcc return valid information – later steps assume all GPU drivers and CUDA libraries are properly installed.

🍷 Install Wine (Staging Version)

Install your distro’s Wine Staging package. This is necessary for Bottles and GPU bridging.

🍾 Bottles Setup

Install Bottles via Flatpak:

flatpak install flathub com.usebottles.bottles

In Manjaro if the flatpak command is not yet available enable Flatpak in the Pamac GUI application. Instead of the terminal you could also use Pamac to search for Bottles and install it through the GUI.

Create and Configure a Bottle

  1. Launch Bottles.

  2. Create a new bottle (e.g., name it 3df).

  3. Under Dependencies, install:

    • VCredist2022

  4. Under Settings, configure:

    • Runner: soda-9.0-1
    • DXVK: dxvk-2.7
    • VKD3D: dxvk-2.7
    • DXVK NVAPI: dxvk-nvapi-v0.9.0 (may not appear until CUDA bridge is set up; come back to this later)
    • Deep Learning Super Sampling: ON (needed to load NVIDIA libraries)
    • Discrete Graphics: ON
    • Synchronization: System
    • Windows Version: Windows: XP, 7, 8, 10 (recommended) and 11 all work. However 11 is still relatively new in Wine - so things might be unstable.
    • DLL Overrides: add nvcuda
    • Environment Variable: add WINE_NVML=1

  5. Click Run Executable in your bottle and install 3DF Zephyr.

⚙️ CUDA Setup

This is the tricky part: connecting native CUDA libraries with your Bottle so it recognizes the GPU.

Step 1: Install Windows CUDA DLLs in Bottle

⚠️This step needs to be done every single time if you create a new bottle, update your Nvidia libraries, or if you change/upgrade your runner.

  1. Go to SveSop/nvidia-libs GitHub and download the latest compiled release.
  2. Follow the instructions in the README, or simply:
cd path/to/nvidia-libs
./bottles_setup.sh 3df # Replace `3df` with your bottle name

Set up the CUDA bridge so Bottles/Wine can redirect DLL calls to your system’s CUDA libraries:

# Enable WINE CUDA bridge
export WINE_NVML=1

# Link native CUDA .so files to Bottle's Windows folders
ln -sf /usr/lib/libcuda.so.1 ~/.var/app/com.usebottles.bottles/data/bottles/bottles/3df/drive_c/windows/system32/libcuda.so
ln -sf /usr/lib/libcuda.so.1 ~/.var/app/com.usebottles.bottles/data/bottles/bottles/3df/drive_c/windows/syswow64/libcuda.so

Adjust paths if your Bottles are stored elsewhere.

Finally, reboot your system to apply changes.

🚀 Run 3DF Zephyr

  1. Open Bottles.
  2. Run your Bottle.
  3. In the terminal type nvidia-smi. If everything worked should be listed in the gpu process list and occupy some vram.
  4. When in 3DF Zephyr go to Tools -> Options -> GPU you should see cuda listed. If you only see OpenCL then you either have installed your Nvidia driver or cuda-toolkit wrong, or your bridge is not setup correctly.

⚠️ Important Notes

  • You won’t see your GPU listed in’s System Info tab.
  • The Log however will show when the CUDA processes are started.
  • To verify GPU usage, run:
nvidia-smi
  • If your gpu is not detected when opening 3DF Zephyr you probably need to redo the CUDA Setup.

3Df Zephyr should appear under active processes. You can also use your local system monitor to see your gpu being used. I really like btop for this!

  • You’ll notice faster compute performance when generating dense point clouds and meshes.

Note: Reboot might take a bit longer after setup. Just wait for your DE or login screen to appear.

🎁 Extra

If you wan’t to integrate the application in your Desktop so that you don’t have to open Bottles everytime.

  • Then simply give bottles acces to the applications folder in /home/user/.local/share/applications/
flatpak override com.usebottles.bottles --user --filesystem=xdg-data/applications
  • In bottles go to your bottle -> 3DF Zephyr and click the 3 dots on the right, then select Add Dekstop Entry

Since no category will be set in the .desktop file that is created, 3DF Zephyr will be listed under "lost and found" in most DE’s.

  • Open the .desktop file in a text editor and replace Categories=Applications with Categories=Graphics;3DGraphics

Happy scanning! -Mark Duisters