How do I install a GUI on my Amazon EC2 instance running Amazon Linux 2?

7 minute read

I want to install a graphical user interface (GUI) in my Amazon Elastic Compute Cloud (Amazon EC2) instance running Amazon Linux 2. How do I do this?

Short description

Before you proceed, first consider one of these alternatives to manually installing a GUI:

  • Launch from an Amazon Linux 2 AMI that comes with MATE pre-installed. For more information, see Configure the Amazon Linux 2 MATE desktop connection.
  • Start using Amazon WorkSpaces, a fully managed, persistent desktop virtualization service. For more information, see Amazon WorkSpaces.
  • Start using NICE DCV, a remote display protocol that delivers remote desktops and application streaming securely from any cloud or data center to any device. For more information, see NICE DCV.

If you want to proceed with manual GUI installation, then do the following:

  1. Install the MATE desktop environment, a lightweight GUI based on GNOME 2 available as an extra for Amazon Linux 2. For more information about MATE, see the MATE desktop environment website.
  2. Install a virtual network computing (VNC) service, such as TigerVNC. For more information about TigerVNC, see the website.
  3. Connect to the GUI using the VNC.
  4. (Optional) Turn off password authentication for VNC.
  5. (Optional) Install a web browser, such as Chromium or Firefox. For more information on Chromium, see the website. For more information on Firefox, see the website. Note that both Chromium and Firefox are only available in the X86 variant.

Note: These instructions apply only to Amazon Linux 2. To confirm the version that you're running, run the following command:

$ grep PRETTY_NAME /etc/os-release
PRETTY_NAME="Amazon Linux 2"

For instructions on accessing an EC2 macOS instance using a GUI, see How can I access my Amazon EC2 Mac instance through a GUI?


Before you begin

1.    Connect to your instance as EC2-user using SSH.

The instance must be in a public subnet and accessible through a public IP address or an Elastic IP address. Or, you can establish a connection using AWS VPN or AWS Direct Connect that allows you to access your instance through a private IP. These instructions don't apply to environments using a bastion host. For security reasons, traffic to the VNC server is tunneled using SSH. It's a best practice to avoid opening VNC ports in your security groups.

2.    Update your instance by running sudo yum update, and then reboot the instance. Failure to update and reboot can lead to unpredictable results when following these steps.

Install the MATE desktop environment

1.    Install MATE packages.

sudo amazon-linux-extras install mate-desktop1.x

2.    Define MATE as your default desktop for all users.

sudo bash -c 'echo PREFERRED=/usr/bin/mate-session > /etc/sysconfig/desktop'

Install TigerVNC

1.    Install TigerVNC Server:

sudo yum install tigervnc-server

2.    Configure a VNC-specific password containing from six to eight characters for this user. When asked if you want to enter a view-only password, press "n".


3.    Restrict VNC network access to the localhost, so that VNC can be accessed only by using a secure SSH tunnel.

Create the tigervnc configuration directory:

sudo mkdir /etc/tigervnc

Create a mandatory configuration file containing the localhost option:

sudo bash -c 'echo localhost > /etc/tigervnc/vncserver-config-mandatory'

4.    Start the VNC Server on display number 1, and cause it to always start at boot time.

Create a new systemd unit.

sudo cp /lib/systemd/system/vncserver@.service /etc/systemd/system/vncserver@.service

Use the sed command to replace all occurrences of USER in the new unit with ec2-user.

sudo sed -i 's/<USER>/ec2-user/' /etc/systemd/system/vncserver@.service

Reload the systemd manager configuration.

sudo systemctl daemon-reload

Turn on the service.

sudo systemctl enable vncserver@:1

Start the service.

sudo systemctl start vncserver@:1

Connect to the GUI using VNC

1.    Install the TigerVNC software on your local computer, if it's not already installed. TigerVNC is available for Windows, Linux, and macOS. See the TigerVNC website to access the download.

Linux: The tigervnc package is available in the repositories of many distributions, and can be installed using their respective package managers.

macOS: Download and install TigerVNC-x.y.z.dmg, where x.y.z represents the latest version.**
Windows:** Download and install tigervnc64-x.y.z.exe (64-bit) or tigervnc-x.y.z.exe (32-bit), where x.y.z represents the latest version.

2.    On your local computer, use SSH to connect to your instance while creating a tunnel to forward all traffic on local port 5901/TCP (VNC) to the instance's VNC server:

Linux and macOS

When connecting to your instance using SSH, add the -L parameter to activate port forwarding. Replace PEM_FILE with your private key, and INSTANCE_IP with your instance's public or private IP, as appropriate.

ssh -L 5901:localhost:5901 -i PEM_FILE ec2-user@INSTANCE_IP


When opening the connection with PuTTY, configure port forwarding, and then open the connection:

  1. From the Connection menu, select SSH, and then select Tunnels.
  2. Enter 5901 in the Source Port field.
  3. Enter localhost:5901 in the Destination field.
  4. Select Add.

3.    Open the TigerVNC Viewer on your local computer. When asked for the VNC server hostname, enter localhost:1 and then connect to it.

4.    Enter the VNC password that you set up in step 2 of the Install TigerVNC section. If an alert appears stating that the connection isn't secure, disregard it. You're accessing the VNC server using an encrypted SSH tunnel.

Your MATE desktop environment appears.

(Optional) Turn off password authentication for VNC

It's not a best practice to turn off VNC password authentication. Any users who are able to use SSH to connect into your instance will be able to create a tunnel and access your VNC desktop. If this is a single-user instance (that is, no other people can log in), and you'd like to turn off password authentication for VNC anyway, follow these steps:

1.    Change the Security Types setting of the VNC Server to None:

echo SecurityTypes=None >> ~/.vnc/config

2.    Restart the VNC server.

sudo systemctl restart vncserver@:1

(Optional) Install a web browser (X86 only)

AWS doesn't provide web browsers such as Chromium or Firefox in Amazon Linux 2 repositories. To install one of these browsers, follow these steps. Note that AWS doesn't provide support for software installed from third-party sources.

The following instructions apply to EC2 instances based on 64-bit Intel and AMD processors (x86_64). These third-party sources don't provide web browsers for instances based on Graviton processors (aarch64). To confirm your instance's architecture, run the following command:

$ uname -m

To install Chromium (open-source project behind Google Chrome), do the following:

1.    Activate the EPEL repository. See the EPEL documentation on the website for more information.

sudo amazon-linux-extras install epel

2.    Install Chromium packages.

sudo yum install chromium

Chromium installs on MATE under Applications, Internet, Chromium Web Browser.

To install Mozilla Firefox (for current user only), do the following:

1.    Download the latest Firefox version for Linux 64-bit to your local computer. See the website to access the download.

2.    After downloading Firefox, copy the file to your instance. See the respective websites for Linux and Windows for instructions.

3.    Connect to your EC2 instance using SSH.

4.    Extract the file contents. This example command indicates that the file is in the ec2-user's home directory. Change the path and the Firefox version as needed.

tar jxf ~/firefox-xx.y.tar.bz2 -C ~/

5.    Using vim or your favorite editor, create a desktop icon. Create the file ~/Desktop/Firefox.desktop with the contents as shown in the following example.

[Desktop Entry]
Comment[en_US]=Firefox web browser
Comment=Firefox web browser
GenericName[en_US.UTF-8]=Firefox web browser

6.    Use the desktop icon that you created in step 5 to launch Firefox.

7.    If a prompt appears about the application launcher not being marked as trusted, choose Mark as Trusted, and then double-click to open Firefox.

AWS OFFICIALUpdated 2 years ago

I keep getting following error. Could you help? Trying to connect via TigerVNC from Windows 10 to Amazon Linux 2. Putty connections works just fine.

2023-03-22 16:21:35 Opening connection to localhost:5901 for forwarding from [::1]:62131

2023-03-22 16:21:35 Forwarded connection refused by remote: Connect failed [Connection refused]

replied a year ago

Thank you for your comment. We'll review and update the Knowledge Center article as needed.

profile pictureAWS
replied a year ago

I have followed all instructions in this article, but when I connect via TigerVNC I get an empty screen. Meaning, the connection is successful but nothing appears on screen.

I am running CIS Amazon Linux 2 Kernel 5.10 Benchmark v1.0.0.14 - Level 1-abcfcbaf-134e-4639-a7b4-fd285b9fcf0a (ami ID ami-0547e646fff07d3e3)

replied a year ago

Thank you for your comment. We'll review and update the Knowledge Center article as needed.

profile pictureAWS
replied a year ago

This guide is outdated. amazon-linux-extras no longer exists in Amazon Linux 2023

replied a year ago

Thank you for your comment. We'll review and update the Knowledge Center article as needed.

profile pictureAWS
replied a year ago

Is there an updated quide?

replied a year ago

Thank you for your comment. We'll review and update the Knowledge Center article as needed.

profile pictureAWS
replied a year ago

Tried using the latest AMI with MATE desktop connection but the GLIBC libraries are at 2.26 which is too old not not a viable solution

replied 5 months ago

Thank you for your comment. We'll review and update the Knowledge Center article as needed.

profile pictureAWS
replied 5 months ago