When working in a remote environment,
this extension sets the
DISPLAY environment variable so that X windows
applications started from Visual Studio Code appear on the local machine.
For this extension to work, it must be installed on the remote machine, and you
must be running an X server on the local machine. For SSH connections, the
Remote X11 (SSH)
extension must also be installed on the local machine (this should be installed
automatically when you install this extension).
You may need to change some settings for this to work with SSH! Please check
the "Authentication Settings" section below, as this extension cannot use VS Code's
SSH authentication, and it does not support all SSH authentication methods.
For Windows hosts, this extension has only been tested with VcXsrv,
but other servers such as Cygwin/X, Xming,
and X410 should also work. Windows remotes are
not currently supported.
For SSH connections, if the remote machine does not have Bash installed, you
must change the
remoteX11.SSH.displayCommand setting and provide a command
that prints the value of the
DISPLAY variable. If you are using port
forwarding, you may also need to change the
remoteX11.SSH.port setting. See
below for more details.
For containers and WSL 2, you will need to either
authorize with your X server
or disable access control.
For SSH and WSL 1 targets, connections to the X server will come from the local
machine, so you should not need to configure anything for these to work.
The Remote - SSH extension does
not currently enable X11 forwarding ([see issue #267](https://github.com/microsoft/vscode-remote-release/issues/267)).
To work around this, the Remote X11 (SSH)
extension creates an SSH connection to the remote machine with forwarding
enabled in the background.
This extension currently only supports public key authentication. See below
for more details on authentication settings.
Changes to settings will normally apply automatically after a short delay. You
may need to restart any terminals if setting changes result in the
You can also use
F1 > Remote X11: Reconnect Display to force an update.
remoteX11.display - Display number to connect to. Change this if your X server
is using a display other than 0.
remoteX11.screen - Screen number to connect to.
remoteX11.container.enable - Set
DISPLAY for containers?
remoteX11.SSH.enable - Enable X11 forwarding and set
DISPLAY for SSH targets?
keyFile - Authenticate with the private key file specified by
Passphrase-protected keys are not supported.
agent - Use
ssh-agent to get keys. This method does support passphrase-protected keys.
remoteX11.SSH.agent - Name of a Unix socket or Windows named pipe for ssh-agent.
pageant to use Pageant on Windows. If left empty, defaults to Windows 10's OpenSSH
\\.\pipe\openssh-ssh-agent) or the
SSH_AUTH_SOCK environment variable on other platforms.
Only used if
remoteX11.SSH.privateKey - Absolute path to your SSH private key file.
Only used if
remoteX11.SSH.XAuthPermissionLevel - Select between untrusted (
ssh -X) and trusted (
ssh -Y) permissions.
remoteX11.SSH.X11ConnectionType - Select between TCP and Unix sockets for the X11 connection.
tcp on Windows hosts or
remoteX11.SSH.X11Socket - Selects the Unix socket to connect to. The screen number is appended to the end of
remoteX11.SSH.displayCommand - A command which prints
DISPLAY=<DISPLAY> followed by a newline,
<DISPLAY> is the value of the
DISPLAY variable. Note that there must not be any spaces
in this text. Change this when connecting to a machine that doesn't support the default command.
remoteX11.SSH.timeout - Number of seconds to wait for the SSH shell to respond to the above command.
0 to wait forever.
remoteX11.SSH.host - Sets the hostname or IP address used to connect to the SSH server.
Use this if Remote X11 tries to connect to the wrong address.
remoteX11.SSH.port - Sets the port used to connect to the SSH server. Use this if
Remote X11 tries to connect to the wrong port.
remoteX11.WSL.enable - Set
DISPLAY for WSL targets?
Remote X11 currently only supports public key authentication. You must use
ssh-keygen to generate a public/private key pair and add your public key to
There are two ways RemoteX11 can be configured to get keys:
Private Key File
remoteX11.SSH.authenticationMethod setting is
keyFile, Remote X11 will
read the file given by the
remoteX11.SSH.privateKey file as your private key.
This defaults to
~/.ssh/id_rsa, so you must change it if your file is named
This method does not support passphrase-protected private keys! See below
for methods that do.
remoteX11.SSH.authenticationMethod setting is
agent, Remote X11 will
ssh-agent to read keys added with
See the VS Code documentation for instructions on enabling the SSH Agent.
To add your key to the SSH agent, open a terminal on the local machine and run:
If your key is passphrase-protected, you will be prompted to enter the passphrase.
You can then log in without re-entering the passphrase.
On Windows, you can also use Pageant
instead of the built-in OpenSSH agent by changing the
Is the extension installed?
When in a remote workspace, open the Extensions view (Ctrl+X) and check that
"Remote X11" is installed and enabled on the remote machine. If you are using an
SSH connection, also check that "Remote X11 (SSH)" is installed and enabled on
the local machine.
Check the logs
When in a remote workspace, open the Output pane (Ctrl+Shift+U) and use the
drop-down list in the upper-right to check the logs from "Remote X11". If
everything is working correctly, the logs should show something similar to:
Setting up display for remote "ssh-remote".
Connecting to SSH user@address port 22
DISPLAY = localhost:11.0
If not, the error message may help you figure out the problem. Solutions to some
common errrors are listed below.
Are the SSH address and port correct?
By default, Remote X11 uses the
SSH_CONNECTION variable to determine the
address and port to the SSH server. This may be incorrect if you are using
features such as port forwarding.
Check the logs for the "connecting to SSH ..." message and check that the
address and port are correct. If not, fix them with the the
remoteX11.SSH.port settings. Note that these settings must be set on
the remote machine, so open a remote workspace and use the Remote tab of
settings to change them.
Is your X server running?
If you see
DISPLAY = ... in the Remote X11 logs but nothing shows up when you
run a GUI application, make sure your X server is running on your local machine.
Also make sure the
remoteX11.display setting matches the display number your
X server is set to use.
Are you using the correct connection type?
X11 servers on Windows typically use a TCP connection, and servers on Unix-based
systems typically use a Unix socket. When
auto, it will select between TCP and Unix sockets accordingly. If the automatic
selection is not correct, you can manually change it to use TCP or Unix sockets.
Is SSH able to find the display?
If you are using SSH and don't see
DISPLAY = ... in the logs, check the logs
from "Remote X11 (SSH)" for errors as well. Near the end of the logs should be
a command to print out the
DISPLAY variable. If this command is failing, try
changing it with the
remoteX11.SSH.displayCommand setting in your user (not
Cannot parse privateKey: Encrypted OpenSSH private key detected, but no passphrase given
Passphrase-protected keys are not supported with the default authentication
method. You must use an SSH Agent instead. See Authentication Settings above
for more details.
All configured authentication methods failed
Check your authentication settings. This usually means that either your public
key is not in the remote server's
authorized_keys file, or you haven't added
your private key to your SSH agent. See Authentication Settings above for
Windows' SSH Agent is probably not running. From the Start menu, open "Services"
and make sure the OpenSSH Authentigation Agent service is running.
Authorization required, but no authorization protocol specified
Access control is enabled on your X server. Either authenticate with the server
or disable access control. See https://en.wikipedia.org/wiki/X_Window_authorization
for more details.
Error: Can't open display: ... on WSL 2
If you get this error when running an application from WSL 2, the connection is
probably being blocked by the Windows firewall. You can edit the firewall rules
to allow it:
From the Start menu, open Windows Defender Firewall, then select "Advanced settings"
from the left sidebar. This should open a window titled "Windows Defender Firewall
with Advanced Security"
Select "Inbound Rules" on the left.
Find the rule with the following settings:
- Name: the name of your X server, e.g. "VcXsrv windows xserver"
- Action: Block
- Protocol: TCP
Right-click the rule and select "Properties".
On the General tab, change the action to "Allow the connection":
On the Scope tab, change "Remote IP address" to "These IP addresses"
and add the following values:
Select OK to save your changes.
See https://github.com/microsoft/WSL/issues/4139 for more details.
If you get any other errors and you can't figure out the cause, create an issue
at https://github.com/ChaosinaCan/vscode-remote-x11/issues and post your logs
and I'll try to help.
If you are using SSH, please enable the
to log technical details about the SSH connection to the "Remote X11 (SSH)" logs,
and include those in your issue report. This is useful for finding issues such
as the server not supporting the algorithm used by your private key.