How to Install and Configure VNC on Debian 11

How to Install and Configure VNC on Debian 11


Virtual Network Computing, or VNC, is a connection system that allows you to use your keyboard and mouse to interact with a graphical desktop environment on a remote server. It helps users who are not yet comfortable with the command line with managing files, software, and settings on a remote server.

In this guide, you’ll set up a VNC server with TightVNC on a Debian 11 server and connect to it securely through an SSH tunnel. Then, you’ll use a VNC client program on your local machine to interact with your server through a graphical desktop environment.


To follow this tutorial, you’ll need:

Once you have everything set up, you can proceed to the first step.

Step 1 — Installing the Desktop Environment and VNC Server

By default, a Debian 11 server does not come with a graphical desktop environment or a VNC server installed, so you’ll begin by installing those.

You have many options when it comes to which VNC server and desktop environment you choose. In this tutorial, you will install packages for the latest Xfce desktop environment and the TightVNC package available from the official Ubuntu repository. Both Xfce and TightVNC are known for being lightweight and fast, which will help ensure that the VNC connection will be smooth and stable even on slower internet connections.

After connecting to your server with SSH, update your list of packages:

  1. sudo apt update

Now install the Xfce desktop environment, along with the xfce4-goodies package, on your server:

  1. sudo apt install xfce4 xfce4-goodies

During installation, you may be prompted to choose a default display manager for Xfce. A display manager is a program that allows you to select and log in to a desktop environment through a graphical interface. You’ll only be using Xfce when you connect with a VNC client, and in these Xfce sessions you’ll already be logged in as your non-root Debian user. So for the purposes of this tutorial, your choice of display manager isn’t pertinent. Select either one and press ENTER.

Once the installation completes, install the TightVNC server:

  1. sudo apt install tightvncserver

Next, install the dbus-x11 dependency to ensure a proper connection to your VNC server:

  1. sudo apt install dbus-x11

To complete the VNC server’s initial configuration after installation, use the vncserver command to set up a secure password and create the initial configuration files:

  1. vncserver

Next there will be a prompt to enter and verify a password to access your machine remotely:

You will require a password to access your desktops. Password: Verify:

The password must be between six and eight characters long. Passwords with more than eight characters will be truncated automatically.

Once you verify the password, you have the option to create a view-only password. Users who log in with the view-only password will not be able to control the VNC instance with their mouse or keyboard. This is a helpful option if you want to demonstrate something to other people using your VNC server, but this isn’t required.

The process then creates the necessary default configuration files and connection information for the server:

Would you like to enter a view-only password (y/n)? n xauth: file /home/sammy/.Xauthority does not exist New 'X' desktop is your_hostname:1 Creating default startup script /home/sammy/.vnc/xstartup Starting applications specified in /home/sammy/.vnc/xstartup Log file is /home/sammy/.vnc/your_hostname:1.log

Next, configure it to launch Xfce and give access to the server through a graphical interface.

Step 2 — Configuring the VNC Server

The VNC server needs to know what commands to execute when it starts up. Specifically, VNC needs to know which graphical desktop it should connect to.

These commands are located in a configuration file called xstartup in the .vnc folder under your home directory. The startup script was created when you ran the vncserver command in the previous step, but you’ll create your own to launch the Xfce desktop.

When VNC is first set up, it launches a default server instance on port 5901. This port is called a display port, and is referred to by VNC as :1. VNC can launch multiple instances on other display ports, like :2, :3, and so on.

Because you are going to change how the VNC server is configured, first stop the VNC server instance that is running on port 5901 with the following command:

  1. vncserver -kill :1

The following is the output with a PID specific to your server environment:

Killing Xtightvnc process ID 17648

Before you modify the xstartup file, back up the original:

  1. mv ~/.vnc/xstartup ~/.vnc/xstartup.bak

Now create a new xstartup file and open it in your preferred text editor:

  1. nano ~/.vnc/xstartup

Commands in this file are executed automatically whenever you start or restart the VNC server. You need VNC to start your desktop environment if it’s not already started. Add the following commands to the file:

xrdb $HOME/.Xresources
startxfce4 &

Here is a brief overview of what each line is doing:

  • #!/bin/bash: The first line is a shebang. In executable plain-text files on *nix platforms, a shebang tells the system what interpreter to pass that file to for execution. In this case, you’re passing the file to the Bash interpreter. This will allow each successive line to be executed as commands, in order.

  • xrdb $HOME/.Xresources: This command tells VNC’s GUI framework to read the user’s .Xresources file. .Xresources is where a user can make changes to certain settings for the graphical desktop, like terminal colors, cursor themes, and font rendering.

  • startxfce4 &: This command tells the server to launch Xfce. This is where you will find all the graphical software that you need to comfortably manage your server.

When you’re finished, save and exit out of your editor. If you’re using nano, you do so by pressing CTRL+X, then Y, then ENTER.

To ensure that the VNC server will be able to use this new startup file properly, you need to make it executable:

  1. sudo chmod +x ~/.vnc/xstartup

Now, restart the VNC server:

  1. vncserver

The output will be similar to the following:

New 'X' desktop is your_hostname:1 Starting applications specified in /home/sammy/.vnc/xstartup Log file is /home/sammy/.vnc/your_hostname:1.log

With the configuration in place, you’re ready to connect to the VNC server from your local machine.

Step 3 — Connecting the VNC Desktop Securely

VNC itself doesn’t use secure protocols when connecting. To connect securely, you’ll use an SSH tunnel to connect to your server, and then tell your VNC client to use that tunnel rather than making a direct connection.

Create an SSH connection on your local computer that securely forwards to the localhost connection for VNC. You can do this via the terminal on Linux or macOS with the following command. Remember to replace sammy and your_server_ip with your non-root username and the IP address of your server:

  1. ssh -L 5901: -C -N -l sammy your_server_ip

Please note there is no output returned after you run this command in your terminal on your local machine. You will have to use a VNC client to view the graphical interface.

Here’s what this ssh command’s options mean:

  • The -L switch specifies the port bindings. In this case you’re binding port 5901 of the remote connection to port 5901 on your local machine.
  • The -C switch enables compression to help minimize resource consumption and speed things up.
  • The -N switch tells ssh that you don’t want to execute a remote command.
  • The -l switch specifies the remote login name. Make sure to replace sammy and your_server_ip with the name of your non-root user and your server’s IP address.

If you are using PuTTY to connect to your server, you can create an SSH tunnel by right-clicking on the top bar of the terminal window, and then select the Change Settings… option:

![Right-click on top bar to reveal Change Settings option](https://assets.digitalocean.com/articles/vnc_2004/vnc_putty_topbar_arrow.png “Right clicking the top bar will reveal the settings option.”)

Find the Connection branch in the tree menu on the left-hand side of the PuTTY Reconfiguration window. Expand the SSH branch and click on Tunnels. On the Options controlling SSH port forwarding screen, enter 5901 as the Source Port and localhost:5901 as the Destination, like in the following:

Adding port forwarding information into PuTTy
Adding the port and destination information into PuTTY

Then click the Add button, and then the Apply button to implement the tunnel.

Once the tunnel is running, use a VNC client to connect to localhost:5901. You’ll be prompted to authenticate using the password you set in Step 1.

Once you are connected, the default Xfce desktop will appear as follows:

The default Xfce graphical interface for the VNC connection to your Debian 11 server
Xfce desktop environment when you first access it via your VNC connection

Select Use default config to configure your desktop.

You can access files in your home directory with the file manager or from the command line, as shown here:

![Searching files via VNC connection to Debian 11](https://assets.digitalocean.com/articles/vnc_debian10/xfce-windows.png “Using the VNC client to search for files.")

On your local machine, press CTRL+C in your terminal to stop the SSH tunnel and return to your prompt. This will disconnect your VNC session.

Next, you will set up the VNC server as a service.

Step 4 — Running VNC as a System Service

Next, you’ll set up the VNC server as a systemd service. You can start, stop, and restart it as needed, like any other service. This will also ensure that VNC starts up when your server reboots.

First, create a new unit file called /etc/systemd/system/vncserver@.service using your preferred text editor:

  1. sudo nano /etc/systemd/system/vncserver@.service

The @ symbol at the end of the name will let you pass in an argument you can use in the service configuration. You’ll use this to specify the VNC display port you want to use when you manage the service.

Add the following lines to the file. Be sure to change the value of User, Group, WorkingDirectory, and the username in the value of PIDFILE to match your username:

Description=Start TightVNC server at startup
After=syslog.target network.target


ExecStartPre=-/usr/bin/vncserver -kill :%i > /dev/null 2>&1
ExecStart=/usr/bin/vncserver -depth 24 -geometry 1280x800 :%i
ExecStop=/usr/bin/vncserver -kill :%i


The ExecStartPre command stops VNC if it’s already running. The ExecStart command starts VNC and sets the color depth to 24-bit color with a resolution of 1280x800. You can modify these startup options as well to meet your needs.

Save and close the file when you’re finished.

Next, make the system aware of the new unit file:

  1. sudo systemctl daemon-reload

Then, enable the unit file:

  1. sudo systemctl enable vncserver@1.service

The 1 following the @ sign signifies which display number the service should appear over, in this case the default :1 as was discussed in Step 2.

Stop the current instance of the VNC server if it’s still running:

  1. vncserver -kill :1

Then start it as you would start any other systemd service:

  1. sudo systemctl start vncserver@1

You can verify that it started with the following command:

  1. sudo systemctl status vncserver@1

If it started correctly, the output will be similar to the following:

● vncserver@1.service - Start TightVNC server at startup Loaded: loaded (/etc/systemd/system/vncserver@.service; enabled; vendor preset: enabled) Active: active (running) since Fri 2022-08-19 16:21:36 UTC; 5s ago Process: 24469 ExecStartPre=/usr/bin/vncserver -kill :1 > /dev/null 2>&1 (code=exited, status=2) Process: 24474 ExecStart=/usr/bin/vncserver -depth 24 -geometry 1280x800 -localhost :1 (code=exited, status=0/SUCCESS) Main PID: 24482 (Xtightvnc) . . .

Your VNC server will now be available when you reboot the machine.

Start your SSH tunnel again:

  1. ssh -L 5901: -C -N -l sammy your_server_ip

Then make a new connection using your VNC client software to localhost:5901 to connect to your machine.


You now have a secured VNC server up and running on your Debian 11 server. Now you’re able to manage your files, software, and settings with a user-friendly and familiar graphical interface. You can also run graphical software like web browsers remotely.

Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.

Learn more about our products

About the authors
Default avatar


Default avatar
Kong Yang


Still looking for an answer?

Ask a questionSearch for more help

Was this helpful?

This textbox defaults to using Markdown to format your answer.

You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!

please add version for debian 12 here


this not work for debian 12 return error (write in french)

impossible de contacter le serveur de configuration

Unable to contact configuration server (english translated by google)

impossible de se connecter permissions non accordé

Unable to connect permissions not granted (english translated by google)

manual start return error

X Server already running on display :1

please solve

for information it is on server and there is not

absolutely no screen and therefore no display :1

Thank you I am newbie to linux but I did work in AIX Unix many many years ago.

Please I am stuck at this step. I had to change the @1 to @2 because I have a PID on 1. Did I state that correctly?

Here is the step

z@debian:~$ sudo systemctl start vncserver@2

Warning: The unit file, source configuration file or drop-ins of vncserver@2.service changed on disk. Run ‘systemctl daemon-reload’ to reload units.

Job for vncserver@2.service failed because the control process exited with error code.

See “systemctl status vncserver@2.service” and “journalctl -xe” for details.

z@debian:~$ journalctl -xe

How can I get this tightvnc to work please. thank you

Hi, thanks for your great manual!

I tried to repeat but got the next screen

strange vnc screen
strange vnc screen

Try DigitalOcean for free

Click below to sign up and get $200 of credit to try our products over 60 days!

Sign up

Join the Tech Talk
Success! Thank you! Please check your email for further details.

Please complete your information!

Featured on Community

Get our biweekly newsletter

Sign up for Infrastructure as a Newsletter.

Hollie's Hub for Good

Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.

Become a contributor

Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.

Welcome to the developer cloud

DigitalOcean makes it simple to launch in the cloud and scale up as you grow — whether you're running one virtual machine or ten thousand.

Learn more
DigitalOcean Cloud Control Panel