Linux uses the DISPLAY environment variable to tell graphical applications where to show their windows. Understanding how to set display environment variable in linux is essential for anyone working with remote servers, containerized applications, or multi-monitor setups. This guide walks you through the entire process with clear steps and real-world examples.
The DISPLAY variable is a core part of the X Window System, which powers graphical interfaces on most Linux distributions. When you run a GUI application, it reads this variable to determine which display server to connect to. If the variable is missing or incorrect, the application will fail with errors like “cannot open display.”
In this article, you will learn the syntax, common use cases, and troubleshooting techniques for setting the DISPLAY variable. Whether you are a beginner or an experienced sysadmin, these instructions will help you get graphical applications running smoothly.
What Is The DISPLAY Environment Variable
The DISPLAY variable follows a specific format: hostname:displaynumber.screennumber. The hostname part is optional and defaults to the local machine. The display number identifies which X server instance to use, while the screen number refers to a specific monitor or virtual screen.
For example, :0 means the first local display, and :0.0 refers to the first screen on that display. On most desktop systems, the default value is :0 or :0.0. Remote connections often use hostname:0.0 where hostname is the remote machine’s address.
Graphical applications like Firefox, GIMP, or terminal emulators all rely on this variable. Without it, they cannot communicate with the X server that manages your screen, keyboard, and mouse.
How To Set Display Environment Variable In Linux
Now lets get to the main topic. The exact process depends on whether you need a temporary or permanent change. Below are the most common methods, each explained with examples.
Temporary Setting Using Export
The quickest way to set the DISPLAY variable is with the export command in your current shell session. This change lasts only until you close the terminal or end the session.
- Open a terminal window.
- Type the following command and press Enter:
export DISPLAY=:0 - Verify the variable is set:
echo $DISPLAY
For a remote display, use the hostname or IP address. For instance, if your remote machine is called “server1,” run:
export DISPLAY=server1:0.0
This method is ideal for testing or one-off commands. You can also combine it with the command you want to run, like this:
DISPLAY=:0 firefox
This sets the variable only for that single command, leaving your shell environment unchanged.
Permanent Setting In Shell Configuration Files
To make the DISPLAY variable persist across terminal sessions, add the export command to your shell’s configuration file. The file depends on which shell you use—typically .bashrc, .bash_profile, or .zshrc.
- Open the configuration file with a text editor:
nano ~/.bashrc - Add this line at the end of the file:
export DISPLAY=:0 - Save the file and exit (in nano, press Ctrl+O, then Ctrl+X).
- Apply the changes:
source ~/.bashrc
For remote setups, you might need to set the variable in .bash_profile instead, as it runs for login shells. If you use Zsh, edit ~/.zshrc with the same syntax.
Be careful with permanent settings. If you set the wrong value, graphical applications may fail to launch. Always test with echo $DISPLAY after making changes.
Setting DISPLAY For SSH Connections
When you connect to a remote Linux machine via SSH and want to run GUI applications, you have two options: enable X11 forwarding or manually set the DISPLAY variable.
X11 forwarding is the cleaner method. Use the -X or -Y flag with SSH:
ssh -X user@remotehost
This automatically sets the DISPLAY variable on the remote machine to point back to your local machine. You can verify with echo $DISPLAY after connecting.
If X11 forwarding is not available, you can manually set the variable. First, find your local machine’s IP address and display number. On your local machine, run:
echo $DISPLAY
Then, on the remote machine, set the variable:
export DISPLAY=192.168.1.100:0.0
Replace the IP address with your actual local IP. Note that this requires your local X server to accept connections from the remote machine, which may involve configuring firewall rules or X server permissions.
Setting DISPLAY In Systemd Services
If you run graphical applications as systemd services, you need to set the DISPLAY variable within the service unit file. This is common for desktop applications that start automatically.
Edit or create a service file in /etc/systemd/system/ or ~/.config/systemd/user/. Add an Environment line under the [Service] section:
[Service] Environment=DISPLAY=:0
For user services, you might also need to set the XAUTHORITY variable. After editing, reload systemd and restart the service:
systemctl --user daemon-reload systemctl --user restart your-service
This ensures the graphical application knows where to display its windows, even when started by the system.
Common Use Cases For Setting DISPLAY
Knowing how to set display environment variable in linux helps in several practical scenarios. Here are the most frequent ones.
Running GUI Apps On A Remote Server
System administrators often need to run graphical tools like GParted or Wireshark on a headless server. By setting the DISPLAY variable to point back to their local machine, they can see the application window locally.
For example, after SSHing with X11 forwarding, you can run:
gparted
The application will appear on your local desktop, even though it is running on the server.
Using Docker Containers With GUI
Docker containers are isolated by default and lack access to the host’s display. To run GUI applications inside a container, you must share the DISPLAY variable and the X11 socket.
Run the container with these options:
docker run -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix your-image
The -e flag passes the host’s DISPLAY value into the container. The volume mount gives the container access to the X server socket.
Multi-Monitor Setups
If you have multiple monitors, each may have a different screen number. You can set the DISPLAY variable to target a specific screen. For instance, to send output to the second monitor, use:
export DISPLAY=:0.1
You can find the available screen numbers with the xrandr command. This is useful for presentations or when you want an application to open on a secondary display.
Troubleshooting DISPLAY Variable Issues
Even with the correct syntax, things can go wrong. Here are common problems and their solutions.
Application Says “Cannot Open Display”
This error usually means the DISPLAY variable is not set or points to an invalid location. First, check the current value:
echo $DISPLAY
If it is empty, set it as described above. If it shows a value, verify that the X server is running and accessible. On the local machine, run:
ps aux | grep Xorg
If no X server is running, you may need to start one or switch to a graphical session.
Permission Denied For X11 Connection
When connecting remotely, you might see “X11 connection rejected because of wrong authentication.” This indicates a permissions issue. On the local machine, run:
xhost +
This disables access control temporarily. For a more secure approach, use xhost +SI:localuser:username to allow specific users.
Alternatively, ensure the ~/.Xauthority file contains the correct cookie. You can copy it from the local machine to the remote one using SCP.
DISPLAY Variable Resets After SSH
Some SSH configurations reset environment variables for security reasons. To preserve the DISPLAY variable, add this line to /etc/ssh/sshd_config on the server:
AcceptEnv DISPLAY
Then restart the SSH service:
sudo systemctl restart sshd
On the client side, ensure your SSH client sends the variable. The -X flag usually handles this automatically.
Advanced DISPLAY Variable Techniques
For power users, there are additional ways to manipulate the DISPLAY variable for specific needs.
Using Multiple Displays With Xephyr
Xephyr is a nested X server that runs inside your existing desktop. You can start it with:
Xephyr :1 -screen 1024x768 &
Then set the DISPLAY variable to :1 to run applications inside the nested window. This is useful for testing or isolating applications.
Setting DISPLAY In Cron Jobs
Cron jobs run with a minimal environment, often missing the DISPLAY variable. To run a GUI application from cron, set the variable explicitly in the command:
0 9 * * * DISPLAY=:0 /usr/bin/gedit
Alternatively, you can source your shell profile before running the command:
0 9 * * * source ~/.bashrc && /usr/bin/gedit
This ensures the DISPLAY variable is available when the job executes.
Using DISPLAY With Wayland
Wayland is replacing X11 on many modern Linux distributions. The DISPLAY variable is not used by Wayland natively. Instead, Wayland applications use the WAYLAND_DISPLAY variable, typically set to wayland-0.
If you run X11 applications under Wayland, the XWayland compatibility layer still uses the DISPLAY variable. In this case, set it to :0 as usual. You can check if XWayland is active with:
ps aux | grep Xwayland
For native Wayland applications, use:
export WAYLAND_DISPLAY=wayland-0
Best Practices For Managing DISPLAY
Follow these guidelines to avoid common pitfalls when working with the DISPLAY variable.
- Always verify the variable after setting it with
echo $DISPLAY. - Use X11 forwarding over SSH instead of manual variable setting when possible.
- For permanent changes, add the export to the appropriate shell configuration file.
- In scripts, check if the variable is set before using it:
if [ -z "$DISPLAY" ]; then export DISPLAY=:0; fi - When troubleshooting, check the X server logs in
/var/log/Xorg.0.log. - For containerized applications, always mount the X11 socket and pass the variable.
By following these practices, you will minimize errors and ensure graphical applications work reliably across different environments.
Frequently Asked Questions
What Does The DISPLAY Environment Variable Do In Linux?
The DISPLAY variable tells graphical applications which X server to connect to. It specifies the host, display number, and screen number where the application should show its windows.
How Do I Check The Current DISPLAY Value?
Run echo $DISPLAY in a terminal. If it returns nothing, the variable is not set. A typical value is :0 or :0.0 for the local display.
Can I Set DISPLAY Permanently For All Users?
Yes, add the export command to a system-wide profile file like /etc/profile or /etc/environment. For example, add DISPLAY=:0 to /etc/environment and reboot.
Why Does My DISPLAY Variable Reset After Logging Out?
This is normal because environment variables are session-specific. To make it persistent, add the export to your shell’s startup file such as .bashrc or .profile.
What Is The Difference Between DISPLAY=:0 And DISPLAY=:0.0?
They are functionally identical. The .0 specifies screen number zero, which is the default. You can omit it unless you have multiple screens and need to target a specific one.
Conclusion
Mastering how to set display environment variable in linux is a fundamental skill for anyone using graphical applications in a Linux environment. Whether you are working locally, remotely, or inside containers, the DISPLAY variable controls where your windows appear.
Start with the temporary export method for quick tests, then move to permanent settings in shell configuration files for consistency. For remote work, X11 forwarding is the recommended approach. Always verify your changes and troubleshoot using the tips provided.
With practice, setting the DISPLAY variable will become second nature. You will be able to run GUI applications anywhere, from headless servers to Docker containers, without frustration. Keep this guide handy for reference, and you will never be stuck with a “cannot open display” error again.