How to Set Up WireGuard on Ubuntu

WireGuard is a small, fast VPN protocol that is built into the Linux kernel, which makes Ubuntu one of the easiest places to run it. A working client takes only a handful of commands and one short text file. The catch is that everything is manual: there is no app to click through, so one wrong character in a key or an address means a silent failure.

This article is a practical walkthrough for Ubuntu users who have a WireGuard configuration from a VPN provider or from a server they run themselves. It covers installing the tools, writing the client config, starting and verifying the tunnel, running it at boot, getting DNS right, and finding the reason when the handshake never happens. It does not compare protocols; for that, read WireGuard vs OpenVPN. If you are an XPASS customer, the supported way to connect is the free VPNclient app, and your My Pass page shows the methods that apply to your account; the Linux help guide covers that route.

What you need before you begin

Gather these items first so you do not stop halfway through.

• An Ubuntu machine running a current release, with a user that can use sudo. The commands below work on Ubuntu 22.04 and later and on most recent Debian-based systems.
• A WireGuard configuration from your provider or your own server. At minimum you need the server's public key, the server's address and UDP port, the tunnel address assigned to you, and the DNS server to use.
• Your own key pair. You generate this on the machine; the private key must never leave it.
• A working base connection. Test that ordinary browsing works before you add a tunnel, so you know whether any later problem belongs to the VPN.

A quick word on the numbers you will see. Tunnel addresses are usually private ones from the ranges in RFC 1918, such as 10.x.x.x. They exist only inside the tunnel and are not your public address. The WireGuard project site documents the design and the cryptography, and the whitepaper explains why the configuration is so short.

Install the packages

Open a terminal and update the package list, then install the tools.

sudo apt update
sudo apt install wireguard wireguard-tools resolvconf

On current Ubuntu, wireguard pulls in what it needs and the module is already in the kernel. The resolvconf package is optional but useful: wg-quick calls it to set DNS when the tunnel comes up. If you already use systemd-resolved, as Ubuntu desktop does by default, install resolvconf anyway only if you see DNS errors later; we cover this in the DNS section.

Confirm the tools are present:

wg --version
wg-quick --help

If both commands answer, the installation is finished. Nothing runs yet; no interface exists until you start one.

Create your keys and the config file

WireGuard identities are key pairs. Generate yours with a restrictive file mask so that only you can read the private key.

umask 077
wg genkey | tee ~/privatekey | wg pubkey > ~/publickey
cat ~/publickey

Send the public key to whoever runs the server, or paste it into the provider's page where it asks for one. Keep the private key file where it is. Never paste it into a chat, a ticket or a public repository.

Now create the configuration file. The file name becomes the interface name, so wg0.conf gives you an interface called wg0.

sudo nano /etc/wireguard/wg0.conf

A client file looks like this, with placeholders in capitals that you replace with your own values:

[Interface]
PrivateKey = YOUR_PRIVATE_KEY
Address = 10.0.0.2/32
DNS = 10.0.0.1

[Peer]
PublicKey = SERVER_PUBLIC_KEY
Endpoint = 203.0.113.10:51820
AllowedIPs = 0.0.0.0/0, ::/0
PersistentKeepalive = 25

What each line does:

• PrivateKey is the content of your private key file.
• Address is the tunnel address your server assigned to you.
• DNS is the resolver to use while the tunnel is up.
• PublicKey under Peer is the server's public key, not yours.
• Endpoint is the server's address and UDP port.
• AllowedIPs decides which traffic goes into the tunnel. 0.0.0.0/0, ::/0 sends everything; a narrower list sends only those networks.
• PersistentKeepalive sends a small packet every 25 seconds so that home routers keep the connection open.

Then tighten the permissions, because the file contains a secret:

sudo chmod 600 /etc/wireguard/wg0.conf

Bring the tunnel up and check it

Start the interface with wg-quick:

sudo wg-quick up wg0

It prints each step as it creates the interface, assigns the address, sets DNS and adds routes. Next, inspect the state:

sudo wg show

Look for three things in the output.

1. A latest handshake line under the peer. If it says a number of seconds ago, the two sides have talked.
2. Transfer counters that increase when you browse. If received stays at zero while sent grows, the server is not answering.
3. The endpoint you expect.

Then verify it does something useful. Check your visible address with your usual method and compare it to what you saw before the tunnel. Open a few sites. Read our guide on checking whether a VPN works for a fuller test list. To stop the tunnel:

sudo wg-quick down wg0

Run a ping to a known address immediately after up to see if traffic flows; if the first ping fails but later pings succeed, that is normal handshake timing, not a fault.

Start the tunnel at boot

If you want the connection restored after every reboot, enable the systemd unit that ships with the package:

sudo systemctl enable --now wg-quick@wg0

Check it with systemctl status wg-quick@wg0. The part after the @ is your config name. To change behaviour later, edit the file and restart the unit with sudo systemctl restart wg-quick@wg0.

Think about whether you truly want always-on on a laptop. If you move between networks, a boot-time tunnel can start before the Wi-Fi is ready and fail, then wait. On a desktop or a server with a stable cable, autostart is convenient. On a laptop, many people prefer starting it by hand or using NetworkManager, which handles roaming better.

Getting DNS right on Ubuntu

DNS is where most "it connects but nothing loads" reports on Ubuntu come from. The DNS = line in the config is applied by wg-quick through whichever tool is present.

Situation	What happens	What to do
resolvconf installed	wg-quick sets DNS through it	Usually works without further changes
systemd-resolved only, no resolvconf	wg-quick may fail to set DNS or print an error	Install resolvconf, or set the DNS with resolvectl
Custom /etc/resolv.conf	wg-quick may overwrite or ignore it	Back up the file and check afterward
No DNS line in config	The system keeps using the local DNS	Add a DNS line if you want queries to follow the tunnel

To see which servers your system is actually using:

resolvectl status

Look for the tunnel interface and its DNS server. If your normal Wi-Fi resolver is still listed first for everything, your queries may bypass the tunnel. Our article on DNS leaks explains why that matters and how to test for it.

Using NetworkManager on a desktop

On Ubuntu desktop, you can import the same file into NetworkManager and manage the tunnel from the network menu, which suits laptops that roam.

sudo nmcli connection import type wireguard file /etc/wireguard/wg0.conf
nmcli connection up wg0

NetworkManager then treats the tunnel as a normal connection, so you can toggle it from the system tray. Two cautions. First, do not run the same tunnel with both wg-quick and NetworkManager at the same time, because they will fight over the interface name. Second, if you import the file, you may remove the wg-quick unit so that only one tool starts it.

Troubleshooting a silent handshake

When wg show lists the peer but no handshake appears, work through this list in order.

1. Check the endpoint. A wrong address or port is the most common error. Copy it again from the provider.
2. Compare keys. Your public key must be registered on the server. The PublicKey in your Peer section must be the server's, not your own.
3. Check the clock. Run timedatectl. A clock that is far off can break the handshake.
4. Test UDP reachability. Some networks block UDP ports. Try a different network, such as a phone hotspot, to see if the handshake appears.
5. Look at the firewall. Ubuntu's UFW, if enabled, allows outgoing traffic by default, but a rule you added earlier may block it. A router or a corporate network may also drop it.
6. Check MTU. If the handshake works but large pages stall, try adding MTU = 1380 under Interface and restart the tunnel. Lower the value further only if the symptom remains.
7. Check the tunnel address. Two devices using the same address cause strange failures. Each device needs its own.

If the interface stays up but internet fails, test with ping -c 3 10.0.0.1 to the tunnel gateway, then with ping -c 3 1.1.1.1 by raw address, then with a name. That sequence separates routing from DNS in a minute.

Safety habits and limits

• Protect the private key. Keep it in a root-only file, back it up securely, and generate a new pair if you suspect exposure.
• One key pair per device. Never copy a config to a second device.
• Know what AllowedIPs does. Sending everything into the tunnel changes your whole machine's traffic path. Sending only some networks leaves the rest outside.
• A tunnel is not a firewall. WireGuard encrypts traffic between you and the server. It does not stop malware or phishing. Read what a VPN cannot protect you from.
• Updates matter. Run sudo apt update && sudo apt upgrade regularly so the kernel and tools stay current.
• Test a speed change fairly. If you want to measure performance, follow our WireGuard speed test guide so the numbers mean something.

Summary

On Ubuntu, a WireGuard client is three steps: install the packages, create a key pair and a short config file, and start it with wg-quick up. Check wg show for a recent handshake, enable the systemd unit if you want it at boot, and handle DNS deliberately with resolvconf or systemd-resolved. When it fails, the usual culprits are the endpoint, the keys, the clock, a blocked UDP port or an MTU mismatch.

If you prefer an app instead of the command line, you can look at the pricing page and use the free VPNclient app with a prepaid pass, which avoids hand-editing config files.