Skip to content
Get packs

Guide · Open source

How to use Gluetun: run a Docker VPN client for other containers

Updated · written with AI from the project's own documentation and checked against our catalogue data

Gluetun is a small VPN client that runs inside a Docker container. You configure it with a supported commercial VPN provider, and it sends the traffic of the container, and of other containers you connect to it, through that VPN. This guide walks through what you need, how to start it with docker compose, and the main options the README describes.

Gluetunpassteque/gluetun · ★ 16k · MIT

Quick start

  1. 1Check prerequisites. Confirm Docker is installed and that you have a subscription with a provider listed in the README.
  2. 2Save the example file. Save the README docker-compose.yml example as docker-compose.yml.
  3. 3Set your provider and credentials. Fill in VPN_SERVICE_PROVIDER, VPN_TYPE and your OpenVPN or WireGuard values.
  4. 4Start the container. Run docker compose up -d from the folder containing the file.
  5. 5Connect other containers or devices. Follow the wiki guide to route other containers or LAN devices through Gluetun.

What you need before you start

Gluetun is set up through Docker and environment variables, so you need Docker installed and a VPN subscription with a supported provider. The README lists providers such as AirVPN, Mullvad, NordVPN, ProtonVPN and Surfshark, among others.

The container needs the NET_ADMIN capability and access to the /dev/net/tun device. If you cannot grant these, Gluetun will not work in your setup.

  • Docker installed and able to run compose files
  • An active subscription with a provider listed in the README
  • Permission to grant NET_ADMIN and /dev/net/tun to the container

Create the docker-compose.yml file

The README provides a basic docker-compose.yml example. Save it as docker-compose.yml in a folder of your choice. Replace the placeholder values, such as the provider name, VPN type and your credentials, with your own.

The example maps HTTP proxy port 8888 and Shadowsocks port 8388, mounts a volume at /yourpath for the /gluetun data folder, and sets VPN_SERVICE_PROVIDER, VPN_TYPE, OPENVPN_USER and OPENVPN_PASSWORD. For WireGuard, the README shows WIREGUARD_PRIVATE_KEY and WIREGUARD_ADDRESSES as commented-out lines.

  • VPN_SERVICE_PROVIDER sets your provider, for example ivpn in the example
  • VPN_TYPE is openvpn or wireguard
  • TZ sets the timezone for accurate log times
  • UPDATER_PERIOD controls how often the server list updates
docker compose up -d

Choose OpenVPN or WireGuard

Gluetun supports OpenVPN for all providers it lists. It also supports WireGuard, but only for some providers natively. For others, the README says WireGuard works through the custom provider option.

Mullvad is listed as WireGuard only. Check the provider list in the README before choosing a protocol, because support differs by provider.

  • OpenVPN: supported for all listed providers
  • WireGuard: native for providers such as Mullvad, NordVPN, ProtonVPN and Surfshark
  • Custom provider: used for providers not in the native WireGuard list, or for custom WireGuard configurations

Connect other containers through Gluetun

The main use of Gluetun is to route other containers through the VPN. The README links to a guide on connecting a container to Gluetun. The example includes a commented container_name line, which must be uncommented to allow external containers to connect.

Once connected, the other container's traffic goes through the VPN. The README also describes connecting LAN devices to Gluetun, which suits home-server setups.

  • Uncomment container_name in the compose file if external containers need to connect
  • Use the linked wiki guide for the connection method

Use the built-in proxies and firewall

Gluetun includes an HTTP proxy, a SOCKS5 proxy and a Shadowsocks proxy that other programs can use. The firewall is a kill switch that only allows traffic through the VPN, to the VPN server, and to allowed LAN devices.

DNS over TLS is built in with the providers you choose, and fine-grained blocking of malicious and ad hostnames and IP addresses is available, with a live update every 24 hours.

  • HTTP proxy tunnels HTTP and HTTPS over TCP
  • SOCKS5 proxy tunnels TCP and UDP
  • Shadowsocks tunnels TCP and UDP, with an encryption layer
  • Kill switch blocks traffic that is not going through the VPN

Find the detailed provider instructions

The README points to the Gluetun wiki for setup, provider-specific instructions and examples, and for common errors and frequently asked questions. The wiki is the official documentation source named in the README.

The README warns that other websites claiming to be official for Gluetun are scams, so use only the repository and the wiki it links to.

  • Wiki: https://github.com/qdm12/gluetun-wiki
  • Common errors and FAQ are in the wiki

What people use it for

  • Send the traffic of a torrent client container through a VPN
  • Route a home-server's LAN devices through a VPN
  • Run apps that should reach the internet only through a VPN
  • Use the HTTP or SOCKS5 proxy for programs that accept a proxy setting

Frequently asked questions

Is Gluetun free?

Gluetun is open source under the MIT licence, as stated in the project's licence section. You still need your own paid subscription with a VPN provider to use it.

What do I need to run Gluetun?

You need Docker and a VPN subscription with a supported provider. The container must be granted the NET_ADMIN capability and the /dev/net/tun device.

Does Gluetun support WireGuard?

Yes. The README says WireGuard works both kernelspace and userspace, with native support for some providers and the custom provider option for others.

Which VPN providers does Gluetun support?

The README lists providers including AirVPN, Mullvad, NordVPN, ProtonVPN, Surfshark and Windscribe, among others. Check the full list in the README before you start.

Can Gluetun work with a provider it does not list?

The README mentions a custom provider option for some providers and custom WireGuard configurations. Use it only if you are comfortable with manual configuration.

How is Gluetun different from Mullvad's official client or wg-easy?

Gluetun is a Docker container that routes other containers and devices through a VPN, configured with environment variables. It is not a graphical desktop app like Mullvad's official client, and it differs from wg-easy, which is a WireGuard setup tool.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Gluetun suits people who run Docker and want one container to send other containers or LAN devices through a supported VPN. It is a poor choice if you want a simple desktop app with a graphical interface, or if you cannot grant the required container permissions, in which case a desktop client such as Mullvad's official app may be easier.

Install options & downloads