Introduction

Vim's built-in Netrw plugin allows browsing remote directories via SCP, SFTP, and other protocols. When remote browsing fails, you get unhelpful errors or a blank buffer:

vim
:e scp://user@remote-server:/var/www/html/
" Shows blank buffer or error:
" netrw is unable to list the directory

This is particularly frustrating because the error messages are vague and do not indicate whether the issue is network, authentication, or configuration.

Symptoms

  • :e scp://user@host:/path/ shows a blank buffer
  • Error: "netrw is unable to list the directory"
  • SSH connection works from the command line but not from Netrw
  • Password prompt appears but authentication fails
  • Directory listing shows but opening files fails

Common Causes

  • SSH key-based authentication not configured for the Netrw session
  • scp command not available in PATH
  • Netrw using wrong SSH method (scp vs sftp)
  • Firewall or SSH configuration blocking the connection
  • Netrw plugin overridden or replaced by a file explorer plugin (NERDTree, nvim-tree)

Step-by-Step Fix

  1. 1.Test SCP connectivity from the command line:
  2. 2.```bash
  3. 3.scp user@remote-server:/var/www/html/ /tmp/
  4. 4.`
  5. 5.If this fails, the issue is with SSH, not Netrw. Fix SSH authentication first.
  6. 6.Configure SSH key-based authentication:
  7. 7.```bash
  8. 8.ssh-keygen -t ed25519
  9. 9.ssh-copy-id user@remote-server
  10. 10.`
  11. 11.Then verify:
  12. 12.```bash
  13. 13.ssh user@remote-server "ls /var/www/html/"
  14. 14.`
  15. 15.Configure Netrw to use the correct method. Add to .vimrc:
  16. 16.```vim
  17. 17." Prefer sftp over scp (more reliable)
  18. 18.let g:netrw_sftp_cmd = 'sftp'

" Enable SSH compression let g:netrw_scp_cmd = 'scp -C'

" Show debug info let g:netrw_keepdir = 0 ```

  1. 1.Use the correct URL syntax:
  2. 2.```vim
  3. 3." Basic SCP browsing
  4. 4.:e scp://user@remote-server//var/www/html/

" Note the double slash before the absolute path " Or with a custom port :e scp://user@remote-server:2222//var/www/html/ ```

  1. 1.Alternative: use sftp directly:
  2. 2.```vim
  3. 3.:e sftp://user@remote-server//var/www/html/
  4. 4.`
  5. 5.Debug Netrw issues by enabling verbose mode:
  6. 6.```vim
  7. 7.:let g:netrw_debug = 1
  8. 8.:e scp://user@remote-server//var/www/html/
  9. 9.:view netrwDebug.log
  10. 10.`

Prevention

  • Set up SSH key-based authentication for all servers you access via Netrw
  • Add SSH host keys to ~/.ssh/known_hosts to avoid interactive prompts
  • Use ~/.ssh/config to define server aliases and connection parameters
  • Consider using sshfs to mount remote directories locally instead of Netrw:
  • ```bash
  • sshfs user@remote-server:/var/www/html /mnt/remote
  • vim /mnt/remote/
  • `
  • Keep Netrw updated with your Vim version - older versions have known bugs
  • If using a file explorer plugin, ensure it does not disable Netrw
  • Document your remote editing workflow and SSH configuration in your team wiki
  • Test remote browsing after SSH configuration changes or server migrations