Setting the DISPLAY variable in Linux directs GUI programs to the correct monitor or remote session. This guide shows you exactly how to set display variable in linux for local and remote use. You’ll learn practical commands, common pitfalls, and troubleshooting tips.
The DISPLAY variable tells X11 applications where to show their windows. Without it set correctly, programs may fail with “cannot open display” errors. Let’s fix that right now.
Understanding The DISPLAY Variable
The DISPLAY variable has a specific format: hostname:displaynumber.screennumber. Usually, it looks like :0 or :0.0 for the local machine. The hostname part is empty for local displays, but required for remote connections.
Each display number represents a separate X server instance. Screen numbers let you target specific monitors within that display. Most systems use :0 as the default.
You can check your current DISPLAY value with echo $DISPLAY. This command prints whatever is currently set, or nothing if it’s empty.
How To Set Display Variable In Linux
Now we get to the core of how to set display variable in linux. There are several methods, depending on your needs. We’ll cover each one step by step.
Temporary Setting For The Current Session
The simplest way is exporting the variable directly in your terminal. This change lasts only until you close that terminal window.
- Open a terminal
- Type:
export DISPLAY=:0 - Press Enter
- Verify with
echo $DISPLAY
For remote sessions, use the remote host’s IP or hostname. Example: export DISPLAY=192.168.1.100:0. This sends GUI output to that machine.
You can also set it for a single command without affecting the shell. Use: DISPLAY=:0 xclock. This runs xclock on display :0 temporarily.
Permanent Setting In Shell Configuration Files
To make the DISPLAY variable persist across sessions, add the export command to your shell’s startup file. Common files include ~/.bashrc, ~/.bash_profile, or ~/.profile.
- Open the file with a text editor:
nano ~/.bashrc - Add this line at the end:
export DISPLAY=:0 - Save and exit
- Reload the file:
source ~/.bashrc
For system-wide settings, edit /etc/environment or /etc/profile. Add the same line there. This affects all users on the system.
Be careful with permanent settings. If you set the wrong display, GUI apps may fail to launch. Always test after making changes.
Setting DISPLAY For SSH Connections
When using SSH with X11 forwarding, the DISPLAY variable is usually set automatically. But sometimes you need to set it manually.
First, enable X11 forwarding in your SSH command: ssh -X user@remotehost. Or use -Y for trusted forwarding. Then check the DISPLAY value on the remote machine.
If it’s not set, export it manually: export DISPLAY=localhost:10.0. The display number often starts at 10 for SSH forwarded sessions.
You can also set it in the SSH config file. Add ForwardX11 yes under the host entry. This automates the process.
Common DISPLAY Variable Formats
Different scenarios require different DISPLAY formats. Here are the most common ones you’ll encounter.
:0or:0.0– Local display, first screen:1– Second local display (if you have multiple X servers)hostname:0– Remote display on a specific hostlocalhost:10.0– SSH forwarded displayunix:0– Local display using Unix domain sockets
Each format tells the X client where to connect. The colon separates the host from the display number. The dot separates display from screen.
Most modern systems use :0 by default. If you have multiple monitors, they usually share the same display number but different screen numbers.
Checking Current DISPLAY Settings
Before changing anything, check what’s currently set. This helps you understand your environment and avoid mistakes.
Use echo $DISPLAY to see the current value. If it’s empty, no display is set. You’ll need to set one before running GUI apps.
You can also check with printenv DISPLAY. This shows the same information. Both commands work in bash and most shells.
For more details about your X server, use xrandr or xwininfo -root. These show connected monitors and display properties.
Troubleshooting DISPLAY Variable Issues
Problems with the DISPLAY variable are common. Here’s how to fix the most frequent errors.
“Cannot Open Display” Error
This error means the DISPLAY variable is missing or incorrect. First, check if it’s set: echo $DISPLAY. If empty, export the correct value.
For local use, try export DISPLAY=:0. For remote, ensure the hostname is reachable and the X server allows connections.
Sometimes the X server needs permission. Use xhost + to allow all connections (not recommended for security). Better to use xhost +local: for local only.
DISPLAY Not Persisting After Reboot
If the DISPLAY variable resets after reboot, you haven’t added it to a startup file. Edit ~/.bashrc or ~/.profile as shown earlier.
Make sure you’re editing the correct file for your shell. Bash uses .bashrc, while Zsh uses .zshrc. Check your shell with echo $SHELL.
Also ensure the file is sourced automatically. Some systems require .bash_profile to source .bashrc explicitly.
Remote DISPLAY Not Working
For remote displays, the X server must accept TCP connections. Modern systems often disable this by default for security.
Edit /etc/ssh/sshd_config and ensure X11Forwarding yes is set. Then restart SSH: sudo systemctl restart sshd.
On the client side, use ssh -X or ssh -Y. The -Y flag trusts the remote client more, which can help with some applications.
Setting DISPLAY For Different Desktop Environments
Different Linux desktop environments may handle DISPLAY differently. Here’s what to know for popular ones.
GNOME
GNOME typically uses :0 for the first session. If you switch users with fast user switching, the second user gets :1.
You can find the correct display by running who or w. These show which display each user session is on.
For Wayland sessions (newer GNOME), the DISPLAY variable might not be set at all. Wayland uses different protocols. Check with echo $WAYLAND_DISPLAY instead.
KDE Plasma
KDE Plasma also uses :0 by default. It works similarly to GNOME for display management.
If you’re using multiple monitors, KDE assigns them to the same display. The DISPLAY variable remains :0 regardless.
For remote access, KDE applications respect the DISPLAY variable just like any other X11 app.
Xfce
Xfce is lightweight and uses standard X11. The DISPLAY variable works exactly as described in this guide.
Xfce sessions often start on :0. If you run multiple sessions, they increment the display number.
Advanced DISPLAY Variable Techniques
Once you master the basics, these advanced techniques give you more control.
Using Multiple Displays
If you have multiple X servers running, you can target specific ones. Start a second X server with startx -- :1. Then set DISPLAY=:1 to run apps there.
This is useful for testing or running separate desktop sessions. Each X server runs independently.
You can also use Xephyr or Xvfb for virtual displays. These don’t require physical hardware.
Setting DISPLAY In Scripts
When writing shell scripts that launch GUI apps, always set the DISPLAY variable explicitly. This prevents errors when the script runs in different environments.
Example: #!/bin/bash export DISPLAY=:0 xclock. This ensures the script always uses the correct display.
For more robust scripts, check if DISPLAY is already set before overriding it. Use conditional logic like if [ -z "$DISPLAY" ]; then export DISPLAY=:0; fi.
Using DISPLAY With Docker
Docker containers don’t have a display by default. To run GUI apps in Docker, you need to share the host’s X socket.
Run the container with: docker run -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix your-image. This passes the DISPLAY variable and mounts the X socket.
You may also need to run xhost +local:docker on the host to allow connections from the container.
Security Considerations For DISPLAY Variable
The DISPLAY variable can be a security risk if misconfigured. Here’s how to stay safe.
Never set DISPLAY=:0 on a remote machine without proper authentication. This allows anyone on the network to connect to your X server.
Use SSH X11 forwarding instead of setting the DISPLAY manually for remote access. SSH encrypts the connection and handles authentication.
If you must allow remote connections, use xhost with specific hosts, not the wildcard +. Example: xhost +192.168.1.100.
Also consider using Xauthority files for authentication. This is more secure than xhost.
Practical Examples Of Setting DISPLAY
Let’s walk through real-world scenarios you’ll encounter.
Example 1: Local GUI App Not Launching
You try to run firefox and get “Error: cannot open display: :0”. Check if DISPLAY is set: echo $DISPLAY. If empty, export it: export DISPLAY=:0. Then run Firefox again.
If it still fails, check if your X server is running. Use ps aux | grep X to see if Xorg is active. If not, start it with startx or log into a graphical session.
Example 2: Running Remote App Locally
You want to run a GUI app from a remote server on your local machine. SSH into the server with ssh -X user@server. Then run the app. The DISPLAY variable should be set automatically to something like localhost:10.0.
If it’s not set, export it manually: export DISPLAY=localhost:10.0. Then run your app. It should appear on your local machine.
Example 3: Multiple Monitor Setup
You have two monitors and want to run an app on the second one. First, find the screen number with xrandr. It shows monitors as eDP-1, HDMI-1, etc.
Set DISPLAY to target a specific screen: export DISPLAY=:0.1 for the second screen. Then launch your app. It should open on that monitor.
Note that not all applications respect the screen number. Some open on the primary monitor regardless.
FAQ: How To Set Display Variable In Linux
How Do I Permanently Set The DISPLAY Variable In Linux?
Add export DISPLAY=:0 to your ~/.bashrc or ~/.profile file. Then run source ~/.bashrc to apply changes. This makes the setting persist across terminal sessions and reboots.
What Is The Default DISPLAY Variable Value In Linux?
The default is usually :0 for the first X server session. If you have multiple sessions, they increment to :1, :2, etc. The exact default depends on your system configuration.
Why Is My DISPLAY Variable Not Set In Linux?
This happens when you’re in a terminal without a graphical session, or when the X server isn’t running. Log into a graphical desktop or start X manually. For SSH sessions, use ssh -X to enable forwarding.
How Do I Set DISPLAY Variable For Root User?
Use sudo with the DISPLAY variable: sudo DISPLAY=:0 command. Or set it in root’s shell config file: sudo nano /root/.bashrc and add the export line. Be cautious running GUI apps as root.
Can I Set DISPLAY Variable In A Script?
Yes, add export DISPLAY=:0 at the beginning of your script. This ensures all GUI commands within the script use the correct display. You can also set it per command: DISPLAY=:0 myapp.
Final Tips For Managing DISPLAY Variable
Always verify your DISPLAY setting after making changes. Use echo $DISPLAY to confirm. Test with a simple app like xclock or xeyes.
Remember that different shells may use different config files. Bash uses .bashrc, Zsh uses .zshrc, and Fish uses config.fish. Edit the right one for your shell.
If you’re using Wayland instead of X11, the DISPLAY variable may not be relevant. Check for WAYLAND_DISPLAY instead. Most modern distributions are transitioning to Wayland.
For complex setups with multiple users or remote access, consider using display managers like GDM or SDDM. They handle DISPLAY configuration automatically.
Finally, don’t forget to restart your terminal or source your config file after making permanent changes. Otherwise, the new setting won’t take effect until your next login.
Now you know exactly how to set display variable in linux for any situation. Whether you’re troubleshooting a local app or setting up remote access, these techniques will work. Practice with the examples and you’ll master it quickly.