Setting Up a WireGuard VPN on a Raspberry Pi

Share what you're reading!

In this tutorial, we will look at how to set up WireGuard VPN on a Raspberry Pi using PiVPN! The goal is to provide easy instructions that will help you set up the WireGuard Raspberry Pi VPN server.

WireGuard is awesome! Up until WireGuard, the gold standard for VPNs has been OpenVPN, which is still a great VPN option. However, WireGuard is a faster alternative that’s somewhat easier to implement.

It also has the benefit of being a lot simpler than OpenVPN, which doesn’t seem important, but it is. If you’re already using OpenVPN, the overall functionality will be similar.

Ultimately, more complex systems have more attack points, so if you care about security, WireGuard might be your answer. It’s important to note that you can install WireGuard on various types of devices.

It’s best to run PiVPN and WireGuard on a Raspberry Pi 4 or 5, but if you have at least a Raspberry Pi 3 B+, that should be fine. This is because only the Raspberry Pi 3 B+ and Raspberry Pi 4 have gigabit ethernet, which is preferable for PiVPN and WireGuard.  

How to Set Up a WireGuard VPN on a Raspberry Pi

Setting up a WireGuard Raspberry Pi VPN Server is a quick and easy process thanks to PiVPN which we will be utilizing in this tutorial.

1. Installing Raspberry Pi OS (Initial Install Steps)

Before you can install WireGuard, you must install the Raspberry Pi OS using the steps below.

1. Navigate to the Raspberry Pi website and download the Raspberry Pi Imager.

how to set up a raspberry pi headless - download page

2. After the download finishes, launch the Raspberry Pi Imager application and connect your SD card to your computer.

raspberry pi imager home screen

3. Select Choose OS and choose the operating system that you would like to use. In this example, I will be using Raspbian Lite.

raspberry pi operating system selector

4. After selecting your operating system, select Choose SD Card and select the SD card that you connected to your machine.

NOTE: This will fully format the SD card so remove any important data prior to proceeding.

storage selection

5. After the operating system and SD card have been selected, select write. This will write the operating system to the SD card.

settings confirmation and write button to write the operating system to the SD card

2. Using PiVPN for WireGuard

We will look at how to set up WireGuard on a Raspberry Pi below using PiVPN.

Thanks to a handy script (PiVPN), installing WireGuard is very simple. Generally, you want to ensure the script you’re running is trusted. This is a known and trusted script, but I still urge you to review it.

1. Open Terminal on your Raspberry Pi and run the command below, which will execute a script to install PiVPN (which has WireGuard built-in).

curl -L | bash
wireguard raspberry pi - running the pivpn command

2. Wait for the process to install the necessary packages. When it’s done, you will be brought to a screen that will inform you that PiVPN will allow you to install OpenVPN or WireGuard. Select OK.

How to Set up a WireGuard VPN Server on a Raspberry Pi - pivpn automated installer screenshot.

3. The next screen will inform you that you need to set a static IP address. It’s best to set a static IP address in your router’s settings, as you are ensuring that DHCP does not try and give this address to any other devices.

However, certain routers (mostly ISP provided ones) do not allow you to complete DHCP reservations. If you can’t set a static IP address for your Raspberry Pi in your router, set a static IP address on the Raspberry Pi by following the instructions.

I specified a static IP address in my router so I am going to skip this step.

viewing the dhcp reservation in pivpn

4. You will now need to select a local user. If you’ve created a different user (outside of the default pi user), you will have the option here.

wireguard raspberry pi - adding a user to pivpn

5. You will be asked to select a VPN type. Select WireGuard.

How to Setup WireGuard on a Raspberry Pi - selecting wireguard in pivpn

6. You might be prompted to install the latest kernel update. If you are, select Yes to proceed. If it doesn’t, skip to the next step to proceed.

NOTE: If you need to update the kernel, you will be required to restart this process after your Raspberry Pi reboots (start from step 1).

wireguard raspberry pi - installing wireguard and proceeding

7. WireGuard will now install.

wireguard raspberry pi isntall

8. You will be asked to enter the port you’d like to use (default is 51820). It’s probably best to keep it as the default, but if you have a reason to change it, you can do that here.

NOTE: This is UDP port 51820.

wireguard raspberry pi - using port 51820 for wireguard

9. Select Yes.

wireguard raspberry pi - confirming port is correct

10. You now need to select the DNS provider you’d like to use. Select Custom if you’d like to use your own DNS server, or any of the public DNS providers if you don’t want to use a local DNS server.

wireguard raspberry pi - selecting a dns provider in pivpn

11. I am using a local Pi-hole DNS server that I already have configured, so I added the IP address there. If you are using a public DNS provider, you can skip this step.

NOTE: The IP addresses (, are my local DNS servers. This will not work for you so ensure you use your local DNS servers or a public DNS provider!

wireguard raspberry pi - adding dns servers in pivpn

12. The DNS servers that you select will now be listed. Select Yes.

wireguard raspberry pi - confirming the vpn servers are correct

13. You will now be prompted to use your public IP address or public DNS entry. If you have a static IP address, you are free to use this address.

However, if you have a dynamic external IP address, you will need to set up DDNS. You can learn how to do that here.

wireguard raspberry pi - specifying a static external IP address or ddns hostname to connect to for clients

14. If you selected to use a dynamic DNS address, you can enter that information here. At the next screen, select Yes to confirm that it is correct.

wireguard raspberry pi - entering the ddns hostname or static IP address

15. You will now be prompted that the server keys will be generated. Select OK. The next step will tell you that the VPN Server will check for unattended-upgrades, and a periodic reboot will be required.

This is a great option. Enable unattended-upgrades (unless you have a good reason not to) and proceed. The packages will now install.

wireguard raspberry pi - confirguring unattended updates so the system stays up to date

16. The installation is now complete! Reboot your system. If you’re using the Raspberry Pi Firewall, make sure you create a rule for UDP port 51820.

confirming installation complete

VPN Connection Types

This section is important for future steps (so you know what kind of profiles you’d like to create). We will be creating either a split-tunnel VPN, a full tunnel VPN, or both in later steps.

Split-Tunnel VPN: Traffic is only sent through your network if it is attempting to access an internal resource. Your IP address when navigating to a site outside of your network will be the IP address of the network that you are currently on.

Full-Tunnel VPN: All traffic is sent through your home network. Your IP address for internal and external requests will be your home network.

I created a very basic image below that explains this, but we will look at how to configure both in later steps. It’s important to note that both connection types will allow you to access your local network. This only shows how traffic is routed differently to external networks.

NOTE: This is not the exact network flow. I am simplifying the process as much as I can.

split-tunnel vs. full-tunnel vpn. full-tunnel routes all traffic through VPN, while split-tunnel only routes local traffic.

3. Configuration File Changes

The two changes that we will make below are in the wg0 config file. Run these commands to open the config file:

sudo su
nano /etc/wireguard/wg0.conf

With the file open, proceed to the next steps.

PostUp & PostDown Rules

This section is a little tricky because these lines will be mandatory if you’re interested in using a split-tunnel VPN profile. If you are using full-tunnel only, there’s a chance that everything will work without adding the PostUp and PostDown lines to the config file. So in summary, add these lines if you intend on using a split-tunnel VPN profile.

If you only intend on using full-tunnel, you might not need to add these lines as all traffic will be routed through your Raspberry Pi. If you don’t add them and you can’t access local resources or connect to the internet when you’re connected to your VPN, come back to this section and add these two lines.

I will do my best to break down everything in these commands so there’s some sort of explanation as to what these changes do.

  • PostUp: command that is executed when you connect to your WireGuard VPN.
    • IPTables: What the system should do with certain packets. A table is created with these rules so the system knows what to do when it receives a packet. These are what the different command-line parameters mean.
    • Masquerade: IP address will be rewritten from source (wg0) to destination (eth0). In layman’s terms, the traffic appears as if it originates from the Raspberry Pi as opposed to the source device. When traffic comes in and is sent to your client device (where you are connected to the VPN), the traffic will have the destination IP rewritten from eth0 (Raspberry Pi) to wg0 (WireGuard network). You still need a static route if you’d like to access your VPN clients!
  • PostDown: command that is executed when you disconnect from your WireGuard VPN to undo everything that we did in the “PostUp” command.

Add these lines to the config file to create an IP table when you connect to WireGuard and masquerade your IP address. NOTE: You might need to change eth0 to be the network interface of your device. However, since you’re using a Raspberry Pi, it’s most likely eth0.

PostUp = iptables -A FORWARD -i wg0 -j ACCEPT; iptables -A FORWARD -o wg0 -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
PostDown = iptables -D FORWARD -i wg0 -j ACCEPT; iptables -D FORWARD -o wg0 -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE

Save the file and exit!

adding postup/postdown rules to the interface in wireguard

4. VPN Profile Creation & Modifications

This is the section where we will create our VPN profiles. I will be creating both, a split-tunnel VPN and a full-tunnel VPN, but feel free to only create profiles for the VPN types you’d like.

1. Run the command below to add a profile.

sudo pivpn add
vpn profile creation in pivpn

2. Navigate to the configs folder. There will be two config files, one for our split-tunnel profile and one for our full-tunnel.

cd configs
navigating to the configs folder

3. By default, WireGuard is configured as full-tunnel. For this reason, we can leave the full-tunnel file alone and edit the split-tunnel file.

nano PiVPN-ST.conf
creating a client file in pivpn

4. The only change that we have to make here is the AllowedIPs line. By default, AllowedIPs is set as which means that all traffic will go through your home network (full-tunnel VPN). To change this so that only local traffic is sent through WireGuard, we need to change this line to our local IP range.

For most people, it will be or If you aren’t sure what your IP range is, you can look in your router’s configuration under LAN Setup.

If you’d like to have VPN clients talk to each other, you need to add the VPN subnet as well ( Change this file to have your local IP range and save it.

configuring a split-tunnel client

5. The configuration file setup process is now complete!

Persistent Keep-Alive

WireGuard attempts to be as quiet as possible, meaning that it only sends and receives packets when it needs to. For this reason, clients behind a NAT or firewall might be required to keep the connection alive even when it’s not in use. To do this, you need to make a change in the configuration file.

A scenario where this is normally needed is when you have an off-site server that always needs to stay connected to your VPN server. This line will ensure the connection will not close.

1. Run these commands to open the configuration file.

sudo su
nano /etc/wireguard/wg0.conf

2. You will see the VPN profiles that you configured. Add the line below to the profiles where you would like the connection to stay active.

setting a persistent keep alive so the connection stays alive

5. Port Forwarding & Router Changes

We now need to port forward UDP port 51820 on our router to our Raspberry Pi. Port forwarding will be completely different on every brand’s router settings page.

This is a great guide that shows how to port forward on a few different brands of routers, but the best thing to do is try and google the name of your router and port forwarding. Example: Netgear port forwarding

  1. Create a port forwarding rule for UDP port 51820 to your Raspberry Pi’s IP address. In the example below, is the IP address of my Raspberry Pi.
port forwarding rules on router

Static Route Configuration

This step is not required unless you need to access VPN devices from your home network. This is an old screenshot, so ignore the IP addresses listed and ensure you are putting the correct info into yours.

Your home network and VPN network will be on different subnets which means that your local devices will only be able to talk to the machines on its subnet (VPN network will see both).

In order to have your local network talk to your VPN network (in my case, 192.168.1.X and 10.5.0.X), a static route will need to be configured in your router.

I cannot go over the setup steps for this as each router is different, but below is a screenshot of the static route that I configured. The Gateway IP Address will be the IP address of your Raspberry Pi (since that’s where your VPN is running). The subnet is where you will need to enter the IP range you are using (as defined in the WireGuard).

static route settings on router for vpn subnet and local subnet to communicate

6. Accessing/Testing WireGuard VPN Config Files

WireGuard offers applications for almost all devices that you can use. They are fairly basic, but ultimately, you only need to use them to connect to your VPN so there’s no need for them to be complex!

WireGuard Mobile Application

One of my favorite WireGuard features is the ability to generate a QR code and scan that code with your phone. It makes everything so much easier. Not that dealing with config files is particularly hard (and there are situations where you will still need to use config files), but taking out your phone and quickly scanning a QR code is awesome.

If you’d like to generate a QR code to scan, it’s pretty easy. First, ensure that you have the WireGuard application installed on your phone or tablet.

1. Run this command to generate a QR code.

pivpn -qr [PROFILE_NAME]
generating a qr code for pivpn

2. A QR code will be generated. Scan this code with your phone, import the profile and you’re done!

NOTE: This QR holds all information to connect to your WireGuard Raspberry Pi VPN. Do not share this image with anyone unless you’d like them to get your VPN profile.

There are situations where the QR code does not pass the correct information to the mobile client. Ensure that the information in the mobile client is correct before proceeding.

3. Scan the QR code with the WireGuard smartphone application. Add the new entry and connect using an outside network. You should be able to connect to all of your local resources!

NOTE: If you test the split-tunnel config file, your external IP address should be your cell phone providers and if you test the full-tunnel, it should be your home ISP’s IP address.

WireGuard PC/Mac Application

If you are setting it up on a PC, you will need to copy the config files over to your device and add them to the application. You can download the application for your device here.

NOTE: You don’t need to physically copy the file, you can simply copy the contents of the file and create your own [VPN_PROFILE].conf file if it’s easier.

WireGuard Performance

You might feel that the performance isn’t as “fast” as you expected. The reason is that you’re limited by the upload speed of your local network and there is a loss in performance from the traffic encryption of the WireGuard VPN server.

For example, if your ISP provides 25Mbps upload speeds, your download speeds through the Raspberry Pi VPN tunnel will be capped at a maximum of 25Mbps (real-world usage will be less).

This doesn’t mean that the performance will be bad, but you will certainly have slower speeds than you would if you were sitting at home on your local network.

Conclusion & Final Thoughts

If you have an old Raspberry Pi laying around or you’re comfortable buying an additional device, this is a great way to use an awesome VPN product with amazing performance. Installing WIreGuard is also a great location to run it as Raspberry Pi devices are extremely energy efficient. You can also connect a second Raspberry Pi to WireGuard if you’d like.


Frank is an IT professional with 14+ years experience and the creator of WunderTech. He focuses on sharing his experience with others on computer hardware, servers, software, networking, and self-hosted apps. He has a BS in Computer Information Systems and an MBA. Learn more about Frank in his bio.