PiVPN: a one-command WireGuard or OpenVPN server on a Raspberry Pi

What PiVPN actually installs, and who it is for

PiVPN is not a VPN protocol and not a daemon. It is a set of shell scripts that install, configure and manage one of two existing servers: WireGuard or OpenVPN. The README describes the primary mission as giving a user "as cost-effective as possible VPN at home without being a technical wizard", which is why the target hardware is a Raspberry Pi and the interface is one installer followed by the pivpn command.

The intended user is someone who already owns a Pi or rents a small Debian or Ubuntu VPS and wants remote access to a home network, or wants their traffic to leave through a provider their ISP cannot inspect. The README gives both cases: a Pi at home to "VPN into your network from not secure remote locations", and a cloud VPS for people with untrustworthy ISPs, where the ISP sees only encrypted traffic.

What you are buying is convenience and defaults. The installer makes the choices (port, protocol, DNS, keys) that you would otherwise assemble from a WireGuard or OpenVPN guide. If you already have a configuration management system, PiVPN duplicates part of it in Bash.

How the installer and the pivpn command divide the work

There are two layers. The first is auto_install/install.sh, which runs once: it checks the host, installs the chosen protocol's packages, writes the server configuration, sets up firewall rules and forwarding, and then places the management scripts. The repository layout reflects this split, with auto_install/ holding the installer, scripts/ holding the day-to-day tooling, files/ holding supporting files, and examples/ holding unattended configuration examples.

The second layer is the pivpn command that the installer leaves behind. The README frames the whole design around it: a one-command installer "followed by easy management of the VPN with the 'pivpn' command". Client creation, client listing, QR codes for mobile clients and revocation belong to that command rather than to the installer.

Because the installer writes the server config itself, the protocol's own configuration files are an output of PiVPN, not its input. That is the trade-off in one sentence: you get a working server quickly, and you also get a layer between you and the WireGuard or OpenVPN configuration that you have to understand before you can change it safely. The README does not document a rollback path for the installer, so treat the host as one you are willing to rebuild.

Installing PiVPN and adding a first client

The README lists three installation methods. The standard one pipes the install script from the project's domain into bash:

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

The direct-link method fetches the same script from the master branch of the GitHub repository:

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

If you would rather read the script before it runs, the clone method is the one to use. It downloads the repository and executes the installer from the local copy:

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

The README also documents a testing variant, `curl -L https://test.pivpn.io | TESTING= bash`, and a developer path that takes `--giturl` and `--gitbranch` arguments so the installer checks out a fork or branch instead of master. Both are described as being for testing changes during development rather than for standard installations.

For repeatable deployments there is an unattended setup, and the repository ships two example files, examples/unattended_openvpn_example.conf and examples/unattended_wireguard_example.conf. The README shows that this config also accepts a custom git source and branch:

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

After the installer finishes, the README's own framing is that management continues through the `pivpn` command: that is where you add clients and produce the configuration or QR code for each device. The README does not list the individual subcommands, so check `pivpn help` or the documentation at docs.pivpn.io before scripting around it.

Where PiVPN stops being the right tool

The first limitation is stated by the project itself. The README opens with a warning that PiVPN is "maintained on a best-effort basis" and points to a release note explaining what that means, with an earlier announcement linked as well. The last push to the repository was on 2026-08-30 and the newest release listed is v4.11.1 from 2025-09-13. That is a project with volunteers behind it, not a vendor with a support contract, and the README says so plainly: "PiVPN is maintained with volunteers free time".

The second limitation is architectural. PiVPN builds a hub: a server that clients connect to. It does not build a mesh between devices that sit behind NAT, and it does not give you identity-based access control across a fleet. If your actual problem is reaching a laptop from a phone when neither is on a network you control, a hub-and-spoke VPN is the wrong shape and you will be fighting the design.

The third is platform drift. The README says PiVPN "should also work" with most Ubuntu and Debian based distributions, including those using UFW by default instead of raw iptables. "Should also work" is the project's own hedge, and firewall handling is exactly the kind of thing that breaks quietly when a distribution changes defaults. The README does not publish a supported distribution matrix; docs.pivpn.io is where that would live.

PiVPN compared with Tailscale

The comparison people search for is PiVPN versus Tailscale, and the difference is not speed or protocol preference. It is who holds the control plane.

With PiVPN, you own everything: the host, the keys, the server configuration, the firewall rules. The README's cloud VPS case makes the consequence explicit, since your traffic exits through the provider you chose and your ISP sees only encrypted traffic. Nothing about your network depends on a third party being reachable, and nothing about it is coordinated by one either. You are responsible for the server staying up, for the port being reachable, and for rotating or revoking clients.

Tailscale takes the opposite approach: devices join a managed coordination service and find each other directly, which is what makes it work between machines behind NAT without a reachable public endpoint. PiVPN has no equivalent of that, because PiVPN is an installer for a conventional VPN server rather than a network overlay. The trade is a dependency on an external service and its account model in exchange for not running a server at all.

A useful way to decide: if you can reach the host from outside on a fixed port, PiVPN is a complete answer. If you cannot, or if the devices you need to connect move between networks, the hub model is the obstacle.

Maintenance, upgrades and the MIT licence

PiVPN is MIT licensed, which is permissive: you can use, modify and redistribute it, including in commercial settings, provided the licence and copyright notice are preserved. That is the whole of the licence implication here; how it interacts with your own distribution or support obligations is a question for your own counsel, not for this article.

Operationally, the upgrade story is thinner than the install story. The README documents four ways to install and a developer path for testing branches, but it does not describe an in-place upgrade procedure, and it does not document rollback. The repository does carry a CHANGELOG.md and the releases are versioned (v4.11.1, v4.11.0, v4.10.1), and the README links a pinned post explaining the best-effort maintenance model, so the release notes are the place to look before changing a working server.

Given that the installer writes server configuration and firewall rules, an upgrade is not a package swap you can reason about from the version number alone. The practical cost of running PiVPN is not the install; it is owning a host whose networking was configured by a script, and being able to reconstruct that configuration if the script's assumptions stop matching your distribution.

Editorial conclusion

PiVPN fits the case where you have a spare Raspberry Pi or a Debian or Ubuntu VPS and want a WireGuard or OpenVPN server without hand-writing configs: one installer, then a pivpn command for clients, QR codes and revocation. It is the wrong tool if you want a mesh network between devices behind NAT, or if you need vendor support and a release cadence you can plan around, since the README states the project is maintained on a best-effort basis by volunteers. Before committing, read the pinned posts in GitHub Discussions, note the last push date of 2026-08-30 and the newest release v4.11.1 from 2025-09-13, and confirm that your host is a supported Debian or Ubuntu based system with the firewall setup the installer expects.

Frequently asked questions

Official sources

1. License: MIT
2. pivpn/pivpn on GitHub
3. Project website
4. README
5. Releases