How to Turn Your Raspberry Pi into a Captive Portal Wi‐Fi Access Point

Wifi Captive Portal Raspberry Pi Raspap

Maybe you’re a business owner who offers complimentary Wi-Fi to all your customers; perhaps you have a captive audience and plan to sell access to your Wi-Fi network, or maybe you want to give guests a friendly reminder about the etiquette of using your home network? You will learn here how to turn your Raspberry Pi into a captive portal Wi-Fi access point.

Why do I need a captive portal?

If you’ve ever tried to access a seemingly-open Wi-Fi network at a cafe, restaurant, hotel or gym, only to be greeted by a login screen that refuses to let you proceed before entering some information (usually your email address), then you’re already familiar with captive portals!

A captive portal is a webpage that either opens automatically in the user’s default browser or loads when they try to visit a webpage. The user will typically need to complete an action before they can move on from the captive portal.

Although they’re commonly used by businesses, captive portals can also be a useful addition to your home network. For example, you can create a separate network for your children, complete with parental controls and a captive portal that gently reminds your children that you’re trusting them to use the web responsibly – just in case they’re tech-savvy enough to know how a VPN works.

What you’ll need

To complete this tutorial, you’ll need:

  • Raspberry Pi that’s running Raspberry Pi OS
  • Power cable that’s compatible with your Raspberry Pi
  • External keyboard and a way to attach it to your Raspberry Pi
  • HDMI or micro HDMI cable, depending on your model of Raspberry Pi
  • External monitor
  • Ethernet cable. Since you’re turning your Raspberry Pi into a wireless access point, you’ll need to connect over Ethernet rather than Wi-Fi. This also means it won’t work with Raspberry Pi 2 or Raspberry Pi Zero since they’re missing either an Ethernet port or wireless card.

Getting started: update your Raspberry Pi

Attach your external keyboard, monitor and ethernet cable, and then attach your Pi to a power source. Once it is booted up, open a terminal and type the following command to update it:

Reboot your Raspberry Pi by running the following command:

Once your Raspberry Pi reboots, everything will be up to date.

Set up wireless access point for Raspberry Pi

There’s several ways to transform your Raspberry Pi into a fully-functioning access point, but in this tutorial a RaspAP is used, as it’s easy to set up.

To install the RaspAP software, open a Terminal window and run the following command:

You can quickly and easily create a Wi-Fi hotspot, using RaspAP

Next, reboot your Raspberry Pi using the following command:

Once your Raspberry Pi is back up and running, your Wi-Fi access point will be configured with the following settings:

  • IP address:
  • Username: admin
  • Password: secret
  • DHCP range: to
  • SSID: raspi-webgui
  • Wi-Fi Password: ChangeMe

To put your access point to the test, simply grab any Wi-Fi-enabled device and check its network settings. You should see the option to connect to a new “raspi-webgui” network.

Open any Wi-Fi enabled device's network settings, and you should see that a new network has appeared!

Connect to this network, and you’ll be prompted for a password. RaspAP’s default password is “ChangeMe,” so type this into the network configuration box, click “Connect” and you’ll be connected to your new Raspberry Pi access point!

Secure your Wi-Fi access point

Before going any further, update “ChangeMe” to something more secure, via the RaspAP web interface:

1. Launch your web browser, if you haven’t already.

2. In the address bar, enter the following:

When prompted, enter the username “admin” and the password “secret.” You should now be viewing the main RaspAP web interface.

The RaspAP web console displays information about your web traffic.

3. In the menu on the left, select “Hotspot -> Security.”

It's recommended that you change your password to something more secure than the publicly-known default!

4. Find the “PSK” section and enter the password that you want to use for your Wi-Fi access point – make sure it’s something secure!

5. Click “Save Settings.”

Creating a captive portal with Nodogsplash

Now that your access point is up and running, you’re ready to secure it with a captive portal.

The captive portal will be built using the Nodogsplash captive portal solution, but first you need to install the libmicrohttpd-dev package, as this contains code that you’ll use to compile Nodogspash.

On your Raspberry Pi, run the following command:

Once you have the libmicrohttpd-dev package, you can clone the repository that contains all the Nodogsplash code:

Once Raspbian has finished cloning this code, you’re ready to compile and install the Nodogsplash software:

Nodogsplash is now installed on your Raspberry Pi.

Configure your captive portal

Next, you need to point Nogdogsplash in the direction of the Gateway address, which is the router interface that’s connected to the local network. RaspAP uses by default, so you need to edit the Nogdogsplash configuration file so that it’s listening on this address.

To edit the Gateway address, open the Nogdogsplash configuration file:

Add the following:

Once you’ve made these changes, save your file by pressing Ctrl + O, followed by Ctrl + X.

Start up your captive portal by running the following command:

Your captive portal is now live. To test it, try connecting to your Wi-Fi hotspot.

If you connect to your Wi-Fi hotspot, you should see the default Nodogsplash captive portal.

You should now be greeted by Nodogsplash’s default captive portal.

Make sure your portal is always online

Now that you’ve checked that the captive portal is working correctly, you need to make sure Nodogsplash starts automatically at boot.

Set Nodogsplash to launch automatically by editing your “rc.local” file. In the Raspberry Pi Terminal, run the following command:

Find the following line:

Directly above it, add the following:

Save your changes by pressing Ctrl + O, followed by Ctrl + X.

How to customize your captive portal

At this point you have a Wi-Fi hotspot that’s protected by a captive portal. However, you’re still using the default Nodogsplash page, so in this final section let’s look at how you can access the code that controls your captive portal page and make some simple edits.

To customize the default Nodogsplash page, you’ll need to open the “splash.html” file:

You can now add images and text to your portal and remove existing content. For example, in the below image the text that’s displayed as part of the captive portal is being changed.

You can customize your captive portal, by editing the splash.html file.

When you’re happy with the edits you’ve made, save your changes by pressing Ctrl + O, followed by Ctrl + X.

Try reconnecting to your Wi-Fi hotspot, and you should see your revamped captive portal.

The next time you try to connect to your Wi-Fi network, you'll see your custom portal screen.

Note that depending on your operating system and web browser, you may need to clear your browser cache in order to see the updated captive portal.

In addition to a Wi-Fi access point, you can also turn your Raspberry Pi into a ad-blocker or a personal web server.

How are you using your newly-created captive portal? To welcome people to your home network, set some ground rules, or as a tool to help promote your business? Let us know in the comments below!

Jessica Thornsby Jessica Thornsby

Jessica Thornsby is a technical writer based in Derbyshire, UK. When she isn’t obsessing over all things tech, she enjoys researching her family tree, and spending far too much time with her house rabbits.


  1. Would this work to make the RPi a completely offline access point? I am preparing for a looooong roadtrip with 3 kiddos, so that they can log into the RPi-network with their tablets and ultimately get access to a harddrive of movies and music. Since I have no ethernet or network to connect to while on the road, the passthru to the internet is not needed.
    Your thoughts are greatly appreciated. (+ note: I’m pretty new to the RPi)

  2. Hi – You could connect a USB hard disk to the Raspberry Pi. However the main challenge would be how to make the files on the USB drive available to the tablets. You would need to use something like Samba or PLEX to serve the media files to the tablets. You may also experience performance issues as the WiFi in the Pi may not be up to serving media files to multiple devices.

  3. Wow, thanks for the great tutorial!

    I did have a question though, I’m planning on also having an offline access point that will redirect users to a webpage with an audio player that will be streaming audio from the RasPi itself, and I was wondering if this would be a good solution for that?

    The main issues that I foresee are that people who connect to this access point won’t be able to access any of their services services while connected to the access point since it’s not connected to the internet, and might forget to disconnect.

    What I’m doing is projecting Halloween decorations into my window, and streaming the music and sound effects to a webpage so that passerby‘s can scan a QR code and auto login to the WiFi access point, and be able to listen to the music and sound effects from the sidewalk on their own devices.

    A captive portal would be nice to warn people to disconnect, but could I use the Capture Portal itself to stream the audio so that users won’t have to fully connect and save/auto-login to the network? Maybe have a disconnect button which is essentially a “cancel” button on most business captive portals that disconnects them?

  4. So here’s the thing. I’ve got to the line:
    On your Raspberry Pi, run the following command:
    sudo apt install git libmicrohttpd-dev

    I open a terminal on my RPi but the apt install can’t resolve

    So somehow I have to get back to using my RPi as a normal device rather than an AP.

    What’s the best way to do that without undoing all the good stuff that works up to have RaspAP showing on


  5. Very very good. After Googling for over 3 hours this article was the best and most straight forward one to use.
    Forgive the question and you may not know but instead of pointing to this html file is it possible to point to a web site hosted via nginx?

    Many thanks anyway. You have given me a great leap forward

  6. I cannot thank you enough for this article. I have been pulling my hair out trying to get something like this working – for days – and I stumbled across this, which is the perfect solution to a major project I am working on.

    I would buy you a pint or three anytime at your pub. My wife is english. Lives near Cannington.

    T H A N K Y O U ! ! ! !

Comments are closed.