Running Julia in a Headless Environment (e.g., tmux)

This follows the earlier post: https://finaiml.com/running-code-on-a-server-with-tmux/

This tutorial explains how to configure Julia and its packages to run in a headless environment, ideal for use in tmux or remote servers without graphical displays.

1. Unset the `DISPLAY` Variable

In a tmux session, ensure that the DISPLAY environment variable is unset to prevent Julia from attempting to connect to a graphical display.

In your Julia session, run:

ENV["DISPLAY"] = nothing

2. Force Offscreen Rendering for Plotting Packages

For GR.jl (Default in `Plots.jl`)

Configure GR to use offscreen rendering:

using GR
ENV["GKS_WSTYPE"] = "100"  # Offscreen rendering

For PyPlot.jl

If you are using PyPlot.jl, set the Agg backend for non-interactive rendering:

using PyPlot
ENV["MPLBACKEND"] = "Agg"

3. Verify the Plotting Backend

If you are using Plots.jl, verify that it is using a non-interactive backend:

using Plots
backend()

The backend should not rely on GUI rendering.

4. Avoid Qt Errors for GR.jl

GR.jl might cause Qt-related errors if required libraries are missing. Install the necessary libraries on your system:

sudo apt-get install libgl1-mesa-glx libglib2.0-0 libxcb-render0 libxcb-shape0 libxcb-xfixes0

Then, explicitly set the GR backend to inline mode in Julia:

using GR
GR.inline()

5. Automate the Configuration

To make these changes permanent, add the settings to your Julia startup file. This ensures they are applied whenever Julia starts.

Create the Julia configuration directory (if it doesn’t already exist):mkdir -p ~/.julia/config
Open (or create) the startup.jl file:nano ~/.julia/config/startup.jl
Add the following content:ENV["DISPLAY"] = nothing ENV["GKS_WSTYPE"] = "100" # GR offscreen rendering ENV["MPLBACKEND"] = "Agg" # PyPlot offscreen rendering
Save and close the file.

6. Restart Julia

Restart your Julia session to apply the changes:

julia

7. Test in a tmux Session

Run your code in a tmux session and ensure that it works without any display-related errors.

For GR.jl:using GR plot(1:10, rand(10))
For PyPlot.jl:using PyPlot plot(1:10, rand(10)) savefig("output.png") # Save plot to a file

Both should render offscreen and not require a graphical display.

Troubleshooting

Still Seeing Display Errors? Ensure you’ve properly unset the DISPLAY variable:println(ENV["DISPLAY"]) # Should output `nothing`
Missing Libraries? If GR.jl or PyPlot.jl reports missing dependencies, ensure they are installed:sudo apt-get install libqt5gui5 libqt5core5a libqt5widgets5

1. Unset the DISPLAY Variable