pivpn: Open Source Networking & Connectivity

What is pivpn?

PiVPN is a set of open-source shell scripts that turns a Raspberry Pi, or an Ubuntu or Debian server, into a self-hosted VPN server running WireGuard or OpenVPN, and it is built for people who want a cost-effective personal VPN at home without having to become a networking expert.

What it is

PiVPN lives in the Raspberry Pi and Debian/Ubuntu Linux ecosystem and is written in Shell, with the codebase itself described as being made with Bash. It is released under the MIT licence, and it exists to turn a Raspberry Pi into a VPN server using two free, open-source protocols: WireGuard and OpenVPN. The project's stated design goal is a one-command installer followed by simple ongoing management of the VPN through the pivpn command. It is explicitly built around a Raspberry Pi costing roughly $35 running the latest Raspberry Pi OS Lite, although the same scripts run on any cloud provider VPS running Ubuntu or Debian, and should work with most Ubuntu and Debian based distributions, including those that use UFW by default instead of raw iptables. Project home is pivpn.io and documentation lives at docs.pivpn.io.

The concrete problem it solves is the manual setup work that OpenVPN and WireGuard normally demand. Standing up either protocol by hand means assembling configuration and hardening decisions that the README describes as requiring a guide or tutorial. PiVPN replaces that manual path with an installer that performs the whole setup itself and applies hardened security settings by default, so the user does not have to tune the server afterward. The project's primary mission is stated plainly: to give a user as cost-effective a VPN at home as possible, using hardware they already own rather than a recurring service.

Key capabilities

Installs and configures either WireGuard or OpenVPN as the server protocol, both being free and open-source.
One-command installation path: curl -L https://install.pivpn.io | bash.
Direct-script alternative that bypasses the install domain: curl https://raw.githubusercontent.com/pivpn/pivpn/master/auto_install/install.sh | bash.
Clone-based installation for users who prefer to inspect the source first: git clone https://github.com/pivpn/pivpn.git followed by bash pivpn/auto_install/install.sh.
Ongoing management of the VPN through the pivpn command rather than by editing server configuration by hand.
Hardened security settings applied by default, with no separate hardening pass required after installation.
Unattended setup support through the pivpnGitUrl and pivpnGitBranch configuration values, plus the --giturl and --gitbranch flags for deploying forks and feature branches non-interactively.
A test and development channel installable with curl -L https://test.pivpn.io | TESTING= bash.

Who uses it and how

Home users running the latest Raspberry Pi OS Lite image on a Raspberry Pi, who want to reach their home network from untrusted remote locations.
Users of cloud provider VPS instances running Ubuntu or Debian, where traffic egresses from the provider and the ISP therefore sees only encrypted traffic, which the README frames as an option for those with untrustworthy ISPs.
Cost-sensitive users, since the project is designed around a Raspberry Pi priced at roughly $35 instead of an ongoing subscription.
Users without a deep networking background: the README states that no guide or tutorial is needed because the installer handles configuration and security defaults.
Community-driven deployments: the project describes itself as purely community-driven, with feedback and support routed through its community.

Getting started

Run curl -L https://install.pivpn.io | bash on a Raspberry Pi running the latest Raspberry Pi OS Lite, or on an Ubuntu or Debian VPS. Alternatively, clone the repository and run bash pivpn/auto_install/install.sh, with full documentation at docs.pivpn.io.

How it compares

The registry entry provides no list of paid products that PiVPN replaces, and no directly comparable installer tool is named in the facts. It therefore stands alone in this registry, and it is worth noting that WireGuard and OpenVPN are the protocols PiVPN deploys rather than products it competes with.

When to use it — and when not to

A self-hoster must supply and operate the underlying host, whether that is a Raspberry Pi or a cloud VPS, along with the Ubuntu or Debian system running beneath it. PiVPN is maintained on a best-effort basis, and the README directs readers to the v4.6.1 release notes for the details of that maintenance model, so anyone needing vendor-backed support or guaranteed response times should look elsewhere. The project carries 14 open issues, and prospective users should read the maintenance statement before committing to it as a long-lived piece of home infrastructure.

project readme (upstream, from github) — read inline

[!WARNING] PiVPN is maintained on a best-effort basis, please read more about it here. Previous announcement is here.

Pivpn Banner

Logos

PIVPN.IO | DOCUMENTATION

PiVPN is a set of shell scripts developed to easily turn your Raspberry Pi (TM) into a VPN server using two free, open-source protocols:

This script's primary mission in life is to allow a user to have as cost-effective as possible VPN at home without being a technical wizard, hence the design of PiVPN to work on a Raspberry Pi ($35) with a one-command installer followed by easy management of the VPN with the 'pivpn' command.

That being said...

PiVPN should be, bar none, the simplest and fastest way to Install and set up an extremely secure OpenVPN or WireGuard server on your Raspberry Pi. You won't need a guide or tutorial as PiVPN will do it all for you in a fraction of the time with hardened security settings in place by default.

We recommend running PiVPN on the latest RaspberryPi OS Lite image in a Raspberry Pi at your home so you can VPN into your network from not secure remote locations and safely use the internet. However, you can also use PiVPN in any Cloud Provider VPS running Ubuntu or Debian to assist those with untrustworthy ISPs. Running a VPN on a server elsewhere means you can connect to the VPN from home, and because your traffic will be getting out from the cloud/VPS provider, your ISP will only see encrypted traffic.

PiVPN should also work with most Ubuntu and Debian based distributions, including those using UFW by default instead of raw iptables.

Installation

Method 1 (standard)

curl -L https://install.pivpn.io | bash

Method 2 (direct link)

curl https://raw.githubusercontent.com/pivpn/pivpn/master/auto_install/install.sh | bash

Method 3 (clone repo)

git clone https://github.com/pivpn/pivpn.git
bash pivpn/auto_install/install.sh

To install from Test/Development branch

curl -L https://test.pivpn.io | TESTING= bash

To install from custom git url and branch (for DEV)

This is inteded to be used when testing changes during development and not for standard installations. Without this the script will always checkout the master branch.

Git repo can be pivpn or any other git repo (e.g. a fork).
Git branch can be specified as required

# Syntax
git clone < customgitrepourl >
bash pivpn/auto_install/install.sh --giturl < customgitrepourl > --gitbranch < customgitbranch >

# Example
git clone https://github.com/userthatforked/pivpn.git
bash pivpn/auto_install/install.sh --giturl https://github.com/userthatforked/pivpn.git --gitbranch myfeaturebranch

The unattended setup config also supports a custom giturl and branch.

pivpnGitUrl="https://github.com/userthatforked/pivpn.git"
pivpnGitBranch="myfeaturebranch"

Feedback & Support

PiVPN is purely community-driven and its our objective for PiVPN to work for as many people as possible. We welcome any feedback on your experience. Please be respectful and be aware PiVPN is maintained with volunteers free time!

General Guidelines

This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to any project maintainer.
You can find our documentation at https://docs.pivpn.io
Please read the pinned posts on Github Discussions
Please search for similar issues, you can search and apply filters that better match the problems you are facing.
Plase search for similar Discussions
If you have not found the answer feel free to open an issue and we will do our best to help out
- Please help us helping you and fill the template adequately providing the requested data Even if it doesn't feel relevant to you
PiVPN team may close any Discussion/Issue without any warning if they don't follow the Guidelines

Contact

Our prefered contact method is through Github Discussions page

But the you can also reach out at:

#pivpn at libera.chat IRC network
#pivpn:matrix.org at matrix.org
Reddit at r/pivpn

Feature requests

Feature requests are very welcome, please do so at:

Feature requests

Bug reports

Make sure the bug is not already reported by searching on GitHub under Issues.
If you could not find an open issue addressing the problem, open a new one.
- Please provide all the data requested on the template Even if it doesn't feel relevant to you and, if possible, a code sample or an executable test case demonstrating the expected behavior that is not occurring.

Pull Requests

Open a new GitHub pull request towards the test branch.
Ensure the PR description clearly describes the problem and solution. Include the relevant issue number if applicable.
Use the following commit rules.
Use the following code style rules.
- We suggest you to use the following shfmt command: shfmt -i 2 -ci -sr -w -bn

Contributions

PiVPN is not taking donations but if you want to show your appreciation, then contribute or leave feedback on suggestions or improvements.

Contributions can come in all kinds of different ways! You don't need to be a developer to help out.

Please check the current issues and discussions. Maybe there is something you can help with
Documentation! Documentation is never good enough! There is always something missing, or typos, or better English!
Our website is also Open Source. feel free to suggest any changes or improvements here
Testing!!! Run pivpn in different ways, different systems, different configurations! Let us know if you find something!
Assisting other users in any of our official channels is also very welcomed

Still, if you consider PiVPN useful and want to Donate instead, then consider donating to:

Frequently asked questions

Is pivpn free to use?

pivpn is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does pivpn do?

The Simplest VPN installer, designed for Raspberry Pi

What is pivpn written in?

pivpn is primarily written in Shell. Its source is publicly available at https://github.com/pivpn/pivpn, and it has 8,043 GitHub stars.