Visual Studio Code Remote-SSH allows you to seamlessly access and manage folders on an Ubuntu server as if they were local. By installing the Remote - SSH extension, you can connect via SSH keys or passwords, browse the remote file system, and edit files directly on the server without manual transfers.
Prerequisites and Installation
Before attempting to connect, ensure that your Ubuntu server has the OpenSSH server installed and running. On the client machine where Visual Studio Code is installed, you must have the
Remote - SSH extension by Microsoft installed from the Extensions marketplace. This extension provides the core functionality for connecting to remote hosts. You also need valid credentials (username and password or SSH key) for the Ubuntu machine. If you are behind a firewall, ensure that port 22 is open for inbound SSH traffic, as discussed in our guide on
Setup SSH Connection with 3 Ubuntu Machines to Bypass a Firewall.
Connecting to the Ubuntu Server
Once the extension is installed, click on the green remote indicator in the bottom-left corner of VS Code. Select
Add New SSH Host. A command palette will appear prompting you to enter the connection string. The format is typically
ssh username@hostname_or_ip. For example, if your user is
dev and the IP is
192.168.1.50, you would type
ssh [email protected]. Press Enter, and VS Code will attempt to establish the connection.
If this is your first time connecting to this host, you may be prompted to select the platform of the remote machine. Choose
Linux since we are accessing an Ubuntu server. VS Code will then upload its server-side components to the remote machine. This process requires root or sudo privileges on the remote side to install the necessary binaries in the
.vscode-server directory within the user's home folder.
Accessing and Navigating Folders
After the initial connection succeeds, you will see a new window titled "Remote-SSH: [hostname]". In the Explorer panel on the left, you can now browse the remote file system. Click the folder icon at the top of the Explorer to open a remote folder. Navigate to the desired directory on the Ubuntu server and select it. VS Code will index the files and make them available for editing.
You can create, delete, rename, and move files just like you would locally. Any changes made in the editor are saved directly to the remote file system. This eliminates the need for FTP clients or manual sync tools. However, large file operations might feel slower due to network latency, so it is advisable to keep the number of open files manageable.
Handling Permissions and Errors
Sometimes, you may encounter permission issues when trying to access certain directories. This often happens if the user does not have read/write access to specific paths. Ensure that your SSH user has appropriate permissions. If you face errors related to file transfers or uploads, check our article on
Unable to Submit Files via Rsync on Ubuntu VPS for troubleshooting steps that often apply to similar permission conflicts.
Another common issue is the "Permission Denied" error during the initial setup of the remote server components. This usually means the SSH key authentication is failing or the user lacks sudo rights. Verify your SSH configuration on the Ubuntu server by checking
/etc/ssh/sshd_config to ensure
PubkeyAuthentication yes is set. Restarting the SSH service with
sudo systemctl restart sshd can also resolve temporary connectivity glitches.
Optimizing Performance
To improve responsiveness, consider adjusting VS Code settings specific to remote connections. In the Settings UI, search for
remote.SSH.remotePlatform and ensure it is correctly set to
{ "linux": true }. You can also tweak
files.watcherExclude to exclude large directories like
node_modules or
.git from being watched, which reduces CPU usage on both local and remote machines.
Additionally, using SSH keys instead of passwords enhances security and speeds up the connection process. Generate an SSH key pair on your local machine using
ssh-keygen and copy the public key to the Ubuntu server using
ssh-copy-id user@host. This method avoids repeated password prompts and provides a more stable connection experience.
Frequently Asked Questions
Why is my VS Code slow when editing remote files?
Slow performance is often caused by network latency or excessive file watching. Exclude large dependencies like
node_modules from the watcher settings to reduce overhead. Ensuring a stable internet connection between your local machine and the Ubuntu server also significantly improves responsiveness.
Can I use VS Code Remote if I don't have sudo access on Ubuntu?
No, the initial setup requires sudo privileges to install the VS Code server components on the remote host. Without these rights, the connection will fail during the installation phase. You must contact your system administrator to grant the necessary permissions or use a different user account with elevated rights.
How do I switch between multiple remote Ubuntu servers?
You can manage multiple hosts by adding each one via the
Add New SSH Host option. Each connection opens in a separate VS Code window, allowing you to work on different projects simultaneously. Switch between windows using your operating system's task switcher or the Window menu in VS Code.
What should I do if I get a 'Connection Refused' error?
A 'Connection Refused' error typically indicates that the SSH service is not running on the Ubuntu server or the port is blocked. Verify that the SSH daemon is active by running
sudo systemctl status sshd on the remote machine. Also, ensure that your firewall allows incoming connections on port 22.
Is it safe to use VS Code Remote over unencrypted networks?
While VS Code Remote uses SSH, which encrypts the data channel, it is still recommended to use it over trusted networks or via a VPN if connecting from public Wi-Fi. Always ensure your SSH keys are secure and never share private keys. Using strong passwords or key-based authentication adds an essential layer of security against unauthorized access.