This document provides an extensive guide on how to install and use ProtonVPN-CLI, as well as explanations about its advanced features and optional enhancements.
- ProtonVPN-CLI Usage Documentation
For the following Linux distribution(s), install the official protonvpn-cli package:
guix install protonvpn-clisudo dnf install -y protonvpn-cliprotonvpn-cli is available for CentOS/RHEL 7.x and 8.x via the EPEL repositories.
For CentOS/RHEL 7.x:
sudo yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
sudo yum install protonvpn-cliFor CentOS/RHEL 8.x:
sudo dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
sudo dnf install -y protonvpn-cliDependencies:
- openvpn
- dialog (optional, needed for interactive selection)
- pip for python3 (pip3)
- python3.5+
- setuptools for python3 (python3-setuptools)
Depending on your distribution, run the appropriate following command to install the necessary dependencies
| Distro | Command |
|---|---|
| Fedora/CentOS/RHEL | sudo dnf install -y openvpn dialog python3-pip python3-setuptools |
| Ubuntu/Linux Mint/Debian and derivatives | sudo apt install -y openvpn dialog python3-pip python3-setuptools |
| OpenSUSE/SLES | sudo zypper in -y openvpn dialog python3-pip python3-setuptools |
| Arch Linux/Manjaro | sudo pacman -S openvpn dialog python-pip python-setuptools |
| Guix | guix environment protonvpn-cli |
Installation happens via Python's package manager PIP.
Note: Make sure to run pip with sudo, so it installs globally and recognizes the command with sudo
sudo pip3 install protonvpn-cli
sudo pip3 install protonvpn-cli --upgrade
If you want to uninstall ProtonVPN-CLI, run protonvpn configure first and purge the configuration. Then uninstall through the package manager you used for installation.
For PIP this would be
sudo pip3 uninstall protonvpn-cli
Bye Bye 😔
If you're having trouble with the normal installation or don't want to install ProtonVPN-CLI as root, follow this guide to install it in a Python virtual environment.
-
Install the virtualenv Python package
pip3 install virtualenv --user -
Create a virtual environment and activate it
virtualenv ~/ProtonVPN-CLIsource ~/ProtonVPN-CLI/bin/activate -
Now that you're in the virtual environment, install ProtonVPN-CLI
pip install protonvpn-cliAs you're in the virtualenv,
pipshould be the same aspip3. -
You should now have the executable
~/ProtonVPN-CLI/bin/protonvpn.which protonvpn -
If that works, deactivate the virtual environment again
deactivate -
Link the executable from above (output of the
whichcommand) to a PATH folder so you can access it from anywheresudo ln -sf ~/ProtonVPN-CLI/bin/protonvpn /usr/local/bin/protonvpn
Now you should be able to use the protonvpn command from anywhere in the system without issues.
-
Activate the virtual environment again
source ~/ProtonVPN-CLI/bin/activate -
Update ProtonVPN-CLI
pip install protonvpn-cli --upgrade -
Deactivate the virtual environment
deactivate
-
Purge configuration
sudo protonvpn configure->7->y -
Delete the ProtonVPN-CLI folder
rm -rf ~/ProtonVPN-CLI -
Delete the symlink
sudo unlink /usr/local/bin/protonvpn
Before you can use ProtonVPN-CLI, you need to initialize it. Run sudo protonvpn init and follow the prompts on the screen.
-
Installing dependencies
To install ProtonVPN-CLI's dependencies, open a terminal and type
sudo apt install -y dialog openvpn python3-pip python3-setuptoolsand confirm with Enter. Wait for the installation to finish -
Installing ProtonVPN-CLI
To install ProtonVPN-CLI type
sudo pip3 install protonvpn-cliin the terminal and confirm with Enter again. It should look something like this:
-
Initialize the ProtonVPN profile
Now you have access to the
protonvpncommand. Before using ProtonVPN-CLI you need to initialize your profile. To do this, typesudo protonvpn initThe client will ask you for your OpenVPN username and password. You can find them at https://account.protonvpn.com/account
Follow the prompts and enter your OpenVPN credentials:
Next, you need to select your plan. If you are currently enjoying the 7-day free trial of ProtonVPN Plus, select
3) Plus.
IMPORTANT: After your trial expires, you will need to reconfigure your plan to 1) Free. To set this up, enter
sudo protonvpn configure. Then select2) ProtonVPN Plan. Finally, select1) Free.Now, you need to choose which default transmission protocol you want to use. UDP is typically the faster option, while TCP is a more reliable protocol that's better suited for unstable connections and in restricted networks. The default selection is UDP.
Finally, confirm your input with
y
-
Connect to ProtonVPN
You are now ready to connect to ProtonVPN. For example, you can let ProtonVPN-CLI find the fastest server for you. Just type
sudo protonvpn connect -fand a connection will be established.
| Command | Description |
|---|---|
protonvpn init |
Initialize ProtonVPN profile. |
protonvpn connect, c |
Select a ProtonVPN server and connect to it. |
protonvpn c [servername] |
Connect to a specified server. |
protonvpn c -r |
Connect to a random server. |
protonvpn c -f |
Connect to the fastest server. |
protonvpn c --p2p |
Connect to the fastest P2P server. |
protonvpn c --cc [countrycode] |
Connect to the fastest server in a specified country. |
protonvpn c --sc |
Connect to the fastest Secure Core server. |
protonvpn reconnect, r |
Reconnect or connect to the last server used. |
protonvpn disconnect, d |
Disconnect the current session. |
protonvpn status, s |
Print connection status. |
protonvpn configure |
Change CLI configuration. |
protonvpn refresh |
Refresh OpenVPN configuration and server data. |
protonvpn examples |
Print example commands. |
protonvpn --version |
Display version. |
protonvpn --help |
Show help message. |
All connect options can be used with the -p flag to explicitly specify which transmission protocol is used for that connection (either udp or tcp).
You can see the full list of commands by running protonvpn --help and a list of examples by running protonvpn examples.
Most of the commands need to be run as root, so use sudo with the commands in this guide!
Before using any other commands, you need to initialize your profile:
protonvpn init
To connect to a server, you always need the connect option (or just c):
protonvpn connect
Running the above command will give you a menu that lets you select the country, server, and transmission protocol interactively:
If you specify a server name after connect, you can connect directly to the server of your choice:
protonvpn connect US-NY#6
The server name can be written in several ways. For example, usny6, us-ny-6 or usny-06 are all valid formats.
To connect to the fastest server, you can use the --fastest or -f flag:
protonvpn c --fastest
protonvpn c -f
You can use the --random or -r flag to connect to a random server:
protonvpn c -r
There are several other variables to keep in mind when you want to connect to the “fastest” server. You can connect to the fastest server in a country, the fastest Secure Core server, the fastest P2P-enabled server, or the fastest Tor server.
Fastest server in a country (replace UK with the code of the desired country, e.g. US for USA, JP for Japan, AU for Australia, etc.):
protonvpn c --cc UK
Fastest Secure Core server:
protonvpn c --sc
Fastest P2P/torrent server:
protonvpn c --p2p
Fastest Tor server:
protonvpn c --tor
All connection methods (except the interactive menu) can be used with the -p flag to choose a transmission protocol. Possible values are either TCP or UDP. If that flag is not used, your connection will use the default transmission protocol you specified during the initialization:
Connect to the fastest server with TCP:
protonvpn c -f -p TCP
Connect to a random server with UDP:
protonvpn c -rp UDP
To disconnect the VPN, you need to use the disconnect or d option:
protonvpn disconnect
protonvpn d
If you're having trouble with your connection, e.g., because you switched networks or your device woke up from sleeping, you can easily reconnect to the last server with the reconnect or r option:
protonvpn reconnect
protonvpn r
If you want to see the status and information of your current connection, you can use the status or s option, which doesn't require root:
protonvpn status
protonvpn s
If you want to change the settings you selected during initialization, you can do this with the configure option, just follow the prompts to change your username/password, default protocol and so on:
protonvpn configure
ProtonVPN-CLI features a DNS Leak Protection feature, which makes sure that your online traffic uses ProtonVPN's DNS Servers. This prevents third parties (like your ISP) from being able to see your DNS queries (and, therefore, your browsing history).
ProtonVPN-CLI accomplishes this by updating the /etc/resolv.conf file when you connect to a VPN server, and makes sure that only ProtonVPN's DNS Server is written in this file. It will also backup the previous state of /etc/resolv.conf to revert all changes upon disconnection.
Please note that if you change your network (e.g., if you connect to a different WiFi hotspot) without first disconnecting, /etc/resolv.conf will likely be updated, which would remove ProtonVPN's DNS Servers. This could cause DNS leaks, so to keep your data safe, use protonvpn reconnect after changing your network.
Enabling DNS Leak Protection
To enable DNS Leak Protection, use the protonvpn configure command, then press 4 to choose DNS Management. Then press 1 to choose that you want to enable DNS Leak Protection.
After you activate this feature, your DNS queries will be secure.
You can also make a custom DNS server your default for all your ProtonVPN connections. ProtonVPN-CLI lets you add up to 3 custom DNS Servers.
Enabling Custom DNS
To configure custom DNS Servers, use the protonvpn configure command, then press 4 to choose DNS Management. Then press 2 to choose that you want to configure a custom DNS Server. Now enter the IP addresses of up to 3 DNS Servers you want to use and confirm with Enter.
If you don't want ProtonVPN-CLI to do any changes to your DNS, you can do this as well. This will cause ProtonVPN-CLI to not touch /etc/resolv.conf and your device will always use the DNS servers configured by you or through your network.
Disabling any DNS management
To enable DNS Leak Protection use the protonvpn configure command, then press 4 to choose DNS Management. Then press 3 to disable any DNS management.
ProtonVPN-CLI features an IPv6 Leak Protection feature. It makes sure that your IPv6 address is not leaked when you connect to a ProtonVPN server.
This feature is enabled by default, and for security reasons, it can't be disabled.
It works by detecting the IPv6 address, backing it up, and removing it from the default interface. When disconnecting, it adds the IPv6 address back to the default interface and deletes the backup.
ProtonVPN-CLI has a built-in Kill Switch that protects your data in case your VPN connection is interrupted or cut unexpectedly.
It works by replacing your existing iptables rules with custom rules that only allow data to go over the OpenVPN interface when the VPN connection is established. When you disconnect, ProtonVPN-CLI will revert iptables back to its previous state.
Enabling Kill Switch
To enable Kill Switch, open the configuration menu with protonvpn configure, then select 5 for Kill Switch and confirm the activation with either 1 or 2, depending on your preference.
1 will block access from your directly connected network (e.g. public WiFi) and is recommended for laptops that may connect to untrusted networks.
2 will allow access from your directly connected network and is for computers that don't leave a secure and trusted LAN, like your home network.
On the next connection Kill Switch will be enabled.
Note: Kill Switch only activates on unexpected connection drops. It will not persist through reboots and not activate when calling protonvpn disconnect. To simulate the Kill Switch, kill the OpenVPN process while connected with sudo pkill openvpn.
ProtonVPN-CLI features IP-based split tunneling. This means that you can exclude specific IP addresses or IP ranges from being routed through the VPN tunnel.
Note: Split Tunneling does not work when the Kill Switch is enabled.
Enable Split Tunneling
To enable Split Tunneling, open the configuration menu with protonvpn configure, then select Split Tunneling with 6. Then confirm with y.
Now add the IPs you want to exclude (one IP at a time) or IP ranges in CIDR notation.
If you want to have a big list of IPs or ranges that you want to exclude, it is recommended to add one IP via the method mentioned above. This will create the file ~/.pvpn-cli/split_tunnel.txt. You can then paste the IPs or networks in CIDR notation in this file, one IP/network per line.
Then call protonvpn refresh to update the OpenVPN template with your excluded IP addresses.
A list of optional enhancements that make using ProtonVPN-CLI easier.
You can disable the prompt for the sudo password when using ProtonVPN-CLI.
-
Enter
sudo which protonvpnto find where the executable is installed
-
Enter
sudo visudoto edit the sudoers file.Go to the bottom of the file and add the following line
user ALL = (root) NOPASSWD: /usr/local/bin/protonvpnNote: Make sure to replace the name
userwith your own username and the path with the output of the previous command -
Save the file
Now you can use ProtonVPN-CLI without entering your password. This is best used with an alias.
An alias lets you access the protonvpn command more quickly and removes the need for you to type sudo all the time. To configure an alias, open your shell's rc file with your favorite editor. For bash, which is the default shell on most Linux distributions, this would be ~/.bashrc. Now add the following lines at the end of the file:
alias protonvpn='sudo protonvpn'
alias pvpn='sudo protonvpn'
This lets you use ProtonVPN-CLI by simply typing protonvpn without sudo or just typing pvpn. For the latter, make sure you have uninstalled the old bash-based ProtonVPN-CLI to avoid complications.
Systemd is the current init system of most major Linux distributions. This guide shows you how to use systemd to automatically connect to a ProtonVPN Server when you boot up your system.
-
Find the location of the executable with
sudo which protonvpn -
Create the unit file in
/etc/systemd/systemsudo nano /etc/systemd/system/protonvpn-autoconnect.service -
Add the following contents to this file
[Unit] Description=ProtonVPN-CLI auto-connect Wants=network-online.target [Service] Type=forking ExecStart=/usr/local/bin/protonvpn connect -f Environment=PVPN_WAIT=300 Environment=PVPN_DEBUG=1 Environment=SUDO_USER=user [Install] WantedBy=multi-user.targetMake sure to replace the username in the
Environment=SUDO_USERline with your own username that has ProtonVPN-CLI configured.PVPN_WAIT=300means that ProtonVPN-CLI will check for 300 Seconds if the internet connection is working before timing out. Adjust this value as you prefer.Also replace the path to the
protonvpnexecutable in theExecStart=line with the output of Step 1.If you want another connect command than fastest as used in this example, just replace
-fwith what you personally prefer. -
Reload the systemd configuration
sudo systemctl daemon-reload. -
Enable the service so it starts on boot
sudo systemctl enable protonvpn-autoconnect
Now ProtonVPN-CLI should connect automatically when you boot up your system.