WiFi setup and troubleshooting

A number of people who have followed the instructions for setting up OctoPi on your Raspberry Pi experience problems getting connected to WiFi. This thread is intended to detail a couple of common problems people have experienced and things to try to resolve them. This page assumes that your WiFi network is up and working and that other devices are able to connect to it without a problem.

We are also assuming that you have already successfully downloaded the OctoPi image and "burned" it on to your SD card. The OctoPi image can be found at https://octoprint.org/download/. The page also includes basic installation directions as well as a video describing installation process. There are also a number of other OctoPrint/OctoPi videos on YouTube which describe basic set-up as well as advanced options.

Basic Setup - Edit Info to Log On to Your WiFi Network

NOTE: there is now an easier way to edit the WiFi settings than the method described below. Instructions for using the Raspberry Pi Imager to download and install OctoPrint and edit the WiFi settings can be found at OctoPrint.org - Download & Setup OctoPrint

I've left the description below for those who prefer to edit WiFi settings via other methods, or who may run into problems and need to adress this by other methods. The trouble-shooting methods found in later sections of this write-up should still be helpful.

:point_up: Heads-up!

Before editing the files noted below, read the troubleshooting section below about using the appropriate text editor while editing this file.

With the SD card plugged in to your computer (you may need an adapter for your computer to accept the SD card if it doesn't already include the appropriate slot). You access the card just as you would an external disk or thumb drive mounted on your computer. The file you will need to edit is in the /boot/ directory of the SD card (if you are editing on a Windows or Mac computer, the /boot/ directory will likely be the only directory you can see.) Look in the "boot" directory of the SD card. The file you need to edit varies depending on which version of OctoPi you downloaded. The process for OctoPi 0.14 and earlier differs from that of OctoPi 0.15 and later. I strongly suggest you use the latest stable release, but descriptions for both are included below. See the section below appropriate to your version.

OctoPi 0.15.0 or newer

In the /boot/ directory, open octopi-wpa-supplicant.txt with the appropriate text editor. (The use of /boot/octopi-network.txt which was used in OctoPi version 0.14 has been discontinued in version 0.15). There are instructions within that file for editing your network settings. Be sure to use an appropriate text editor. For most WiFi networks, you'll edit the section that looks like this:

## WPA/WPA2 secured
#  ssid="put SSID here"
#  psk="put password here"

Uncomment the 4 lines which have a single # front of them by deleting the # (do not delete any spaces after the #), then enter your WiFi network SSID (your network's "name") and the password in the indicated places. Note that the SSID and password are case sensitive. (A common problem when cutting and pasting this information is accidentally including leading or trailing spaces which are not part of the SSID or password.) For a network named JoesWiFi with a password of 12345, it should look like this:

## WPA/WPA2 secured

In OctoPi 0.15, you will also need to set the WiFi Country. The setting for this is also found in the /boot/octopi-wpa-supplicant.txt file. Scroll to near the bottom of the file and find the section that begins with "# Uncomment the country your Pi is in..." By default, the line for the United Kingdom is uncommented (the "#" is removed from the front of the line). If you are in some country other than the UK, comment out the United Kingdom line by putting a # in front of it, then remove the # from in front of the country you are in (do NOT remove the # from the middle of the line). If your country is not in the list, follow the link provided in the file to find the complete list, and create a new line for your country. For example, if you are in Switzerland, you would scroll down the page to find that the 2 letter code is "CH", and create a new line that looks like this:

country=CH # Switzerland

:point_up: Heads-up!

Your WiFi's SSID is hidden? You'll need to to some additional changes or your Pi won't be able to find your network after all!

Within the brackets { ... } add a new line


For example, if it is the WPA/WPA2 section you adjusted earlier, you now want it to look something like this:

## WPA/WPA2 secured

Save the changes and exit the text editor. Do not simply yank the SD card from the reader slot. Find and use the menu command to Eject/unmount the SD card from your computer, wait a few seconds for the unmounting process to complete, and then remove it from the card reader slot. Make sure the Pi is powered down, and then install the SD card in your Pi and boot it up by turning on the power to the Pi. Note that the first boot may take some time: be patient.


Try some of these suggestions if you are unable to connect to your Pi via your Wifi network:

Editing the octopi-wpa-supplicant.txt file (or octopi-network.txt in OctoPi 0.14 or earlier) with the wrong text editor

Some text editors, including Apple's TextEdit (included with macOS) and WordPad (included with Windows) make changes to the files you edit which render them unusable by the Pi's Raspian operating system. (I've heard that Windows NotePad can also cause problems, but have not personally verified that). There are several good, free options out there you can download with will avoid these problems.

For the Mac, I use BBEdit (after 30 days, the freely downloaded version reverts to a limited demonstration version, but that limited version still does everything you need it to to edit files on your Pi.)

For Windows, one of the more popular choices is NotePad++. (also free)

Note that if the file has already been edited with an inappropriate text editor, your best bet is starting over with a clean, unedited copy of that file. Simply editing it again with the correct editor is unlikely to fix the damage.

:spiral_notepad: Note:

If you really want to use Apple's TextEdit on your Mac, it can be fixed by making a few changes to it's default preferences. Launch TextEdit and go to TextEdit>Preferences. Under Format, choose "Plain Text". Under Options, uncheck "Smart Quotes" and "Smart Dashes". Close the preferences pane, then quit TextEdit and relauch. It will now work without messing up your Pi's files. If you have already edited a file before making these changes, you may need to start with a clean copy of the file to get it to work. A telltale sign that TextEdit has screwed up your file: the quotation marks around the SSID and password will show up as "curly" quotes rather than the desired "straight" quotes.

Weak/Inadequate Power Supply

This is a common cause of a wide range of intermittent and hard to diagnose issues, and especially causes problems with the extra load put on the Pi by running WiFi, BlueTooth, a camera, etc.

The Pi needs a solid source of 5+VDC. A minimum of 2 amps. (2.5 Amps is recommended for the Pi 3 and 3B+, particularly if the Pi is powering a camera or USB devices. More recent / more power-hungry models of the Pi make require even higher rated power supplies.)

A charger is not the same as a power supply. Chargers are generally not required to provide tightly regulated voltage or may not be able to provide the peak current that the Pi requires. That old phone charger probably won't work, or if it does, it may cause you intermittent problems. Get an appropriately rated power supply from a reputable source.

Likewise, plugging your Pi into the USB port of your laptop computer is not likely to work reliably. Those ports are usually limited in their current output. If you're lucky, the bare Pi might boot with nothing else attached to it, but WiFi will likely not work, nor things you attach to the Pi's USB port.

On a related note: you need a good quality cable to connect your power supply to the Pi. Many USB cables have conductors that are too small to carry 2.5 amps without an unacceptable voltage drop. A sub-par cable can show the same symptoms as a weak power supply.

Follow this link to find out more about Pi Undervoltage/Power Issues and the little lightning bolt or or thermometer icon that will pop up in the menu bar of a Pi running Octoprint version 1.3.10 or later if it has detected any undervoltage or overtemperature issues:


WiFi signal strength

If you are using the built-in WiFi in a Raspberry Pi-3, a Pi-3B+, or Pi-0W, be aware that the signal strength from the tiny internal antenna may be weaker than other WiFi devices. Try moving your Pi closer to the router as a test (even if that is not possible to do when you are printing, the test will at least let you know if this is the issue). If this solves your connection issue, try relocating your Pi or your router. Sometimes even a small move can make a big difference. Minimize the number of walls or other obstacles blocking the signal, move things out from behind metal boxes or other electrical devices. (My router sat behind a metal electrical service box in my basement. It worked Ok for other devices in my home, but not the Pi. Building a shelf that positioned it just a couple of feet away made a significant difference in signal strength and WiFi reliability for my Pi.)

Hidden SSID

Your WiFi network's SSID might be hidden after all. Please refer to the corresponding Heads-up boxes in the basic setup guide above and adjust the network configuration file (octopi-wpa-supplicant.txt for OctoPi 0.15.0 and newer, octopi-network.txt for OctoPi 0.14 and older) as described there.

Electrical Interference

Electrical interference from some appliances can cause interference with the Pi's WiFi reception. Items such as florescent lights, dimmer switches, some LED lights (typically, it's the power supplies in 110V LED lights, not the lights themselves), some electric motors, etc. Electrically "noisy" devices often create radio frequency interference, which can wreak havoc with the Pi's WiFi signal. This can cause intermittent problems which are hard to diagnose as those appliances turn on and off.

Copying text from places which do not have "Pi-friendly" formatting

(This is an issue with similar symptoms to using the wrong text editor.)

Cutting and pasting commands or text from some sources can cause problems. There can be subtle differences in the text: for example the site from which you copied may have substituted those "curly" shaped quotation marks for the straight ones that the Pi recognizes, or it may have wrapped what should be one long line into two lines (some sites do that wrap without actually causing a break in the line when you copy it - others put a line break in, which messes up the Pi).

Special symbols in WiFi passwords
Another problem that I noticed is the use of the "@" symbol in your WiFi password. For some reason the Pi converts this to a " and thus your wifi log in will not be successful (wrong password). After putting in your SSID and password with something like Raspi-Config, go back and make sure that your @ (ASCII character) is in the correct place and has not been replace by something else. (I used Shift+" on my keyboard to replace the " with a @ but you may have to find a different way or just change your password to something without a @ in it).

The differences can be hard to spot and can have you pulling your hair out. This is one of the reasons it is recommended to put code in a Code Block when posting (that's what the symbol </> in the icon menu above is for).

Copying files vs. burning the image to an SD card

This one is not really a "WiFi" problem, since the Pi won't boot at all in this case, but for someone new to this - especially if they are running a headless set-up, it may appear that their WiFi is not working (in fact, nothing is working).

Some people make the mistake of simply copying the downloaded OctoPi .IMG file to their SD card (for example, by dragging and dropping the file to their card). This is how you install NOOBS, but it will not work to install an .IMG file such as OctoPi. If installed by simply copying to the SD card, the Pi will not boot. One symptom of this is that when you power up the Pi, all that happens is the red light comes on, but you never see the green light flash at all.

OctoPi must be installed by burning the .IMG file to your SD Card. To do this follow the directions on the OctoPi Download Page. Scroll down the page a bit. That page has a link to instructions to install an .img file to an SD card, like any other Raspberry PI image (Do not use a NOOBS-type installation).

:spiral_notepad: Note:

The instructions linked above mention using Etcher (available for Windows, macOS, or Linux) to burn the image to your SD card. Other OctoPi/OctoPrint help videos may mention using Apple Pi Baker (for macOS) or Win32 Disk Imager (for Windows) to burn the image. Any of these will work fine. (I generally use Apple Pi Baker or Win32DiskImager, since they also allow you to make a backup .img file of your SD card, once you have everything set up and working to your liking. Since SD cards can and do fail, having a backup can save you a lot of hassles down the road)

Damaged or defective SD Card

It's possible your SD card is damaged. This can cause all sorts of problems (including failing to boot), not just WiFi issues. The most common cause of SD card failure is probably inserting or removing the SD card while the Pi is powered up. This is a definite no-no. It's also possible (though a bit less likely) to damage the card by not shutting your Pi down properly prior to turning off the power to the Pi (you can shut down from the "System" menu that shows up at the top of the OctoPrint web page if you are logged in as an Admin user, or by entering the sudo shutdown -h now command from the Pi's command line).

You should also use a good quality, class 10 SD card. There are a lot of knock-off or forged cards out there with questionable quality, often masquerading as top brands. Some are not the size they claim to be, and some are just plain poor quality. Save yourself the hassle and buy a reputable brand from a reputable retailer.

Lastly, SD cards can simply wear out over time. The rated read/write cycles are high, but not infinite. If you have a card that has been working but starts getting flaky, it may be time to replace it.

I broke my octopi-wpa-supplicant.txt, can I get a new one?

If you accidentally delete part of the file, or need a correct one to reference, you can find a clean config file here:

OctoPi wpa supplicant clean file (OctoPi 0.17) (gist.github.com)

Other Diagnostic Commands

If all else fails, here are a couple of diagnostic things you can do to help narrow down the problem.

Even if those don't lead to success, please make sure to provide the result of these steps and the output of these diagnostic commands when asking for help on the forums - they will help others help you!

Is your Pi connected to the WiFi network?

There are several ways to check this (note: these are also good ways to find out your Pi's IP address).

Access your router's set-up/control page

If you have access to your router's set up page, there is usually an option to show all connected devices. The details of doing this are beyond what I'll go into here, since each router brand/model is different. In short, you access the page by entering the router's IP address in your web browser's address bar. The IP address varies, but two commonly used setups are and You'll most likely need a username and password to log on to your router (get those from your ISP, if they will give them out). Then poke around the various options. Look for something that says DHCP, or LAN, or WLAN and see if it brings up a list of connected devices. Look for a device named "octopi" in that list (if you have renamed your octopi hostname to something else, look for that name). If you see the name in the list as an active device, your Pi is connected and is using the IP address indicated.

Use a network scanner

There are a number of free apps you can download. I use the free Angry IP Scanner (works on Windows, macOS, and Linux - I have not tried running the Linux version on a Pi). Fing is also a good free option (runs on Windows, macOS, Linux - and has a Pi version. You can also find the Fing app for Android and iOS devices.) Log on to your WiFi network with your computer or phone, launch the app and tell it to scan the network. Look through the result for a device named "octopi" (or whatever name you have given your OctoPi setup). Note that some IP scanners will remember devices from a previous scan and show them even if they are not presently on the network (in this case, usually dimmed out). You are looking for active devices. (If you app shows both active and inactive, yu can usually set a filter to show only active devices.) If you see the name in the list as an active device, your Pi is connected and is using the IP address indicated.

Connect to the Pi via Ethernet or plug in a monitor and keyboard

If your Pi is connected to your local network (or directly to a computer) via an Ethernet cable, you can SSH into it to enter commands on the command line. You can also access the Pi by plugging in a keyboard and monitor. In either case, log into your Pi and enter the following command:

ifconfig wlan0

If your Pi is connected to the WiFi network, the beginning of the output should look something like this:

wlan0     Link encap:Ethernet  HWaddr xx:yy:zz
          inet addr:192.168.aa.bb  (followed by other stuff)

The four-part number is the IP address assigned to your Pi by your router for WiFi access. (The "192.168." start of the number is a very common sequence for home WiFi networks. The "aa.bb" part may be a variety of numbers. Another common starting number sequence is "10.". Unless you have an unusual network/router setup, yours will likely look similar. Large corporate or school networks will likely be different.)

If the Pi is not connected to a WiFi network, the beginning of the output from that command will likely look something like this:

wlan0     Link encap:Ethernet  HWaddr xx:yy:zz
          UP BROADCAST MULTICAST  MTU:1500  Metric:1

In other words, there's no line listing "inet addr:" for wlan0.

Can your Pi even see your WiFi network?

If you are able to log into your Pi through an Ethernet connection or with an attached monitor and USB keyboard, the following command will show all of the WiFi networks your Pi can see (whether it can connect to them or not):

sudo iwlist wlan0 scan

If this produces MANY screens of output, you can fix it by using

sudo iwlist wlan0 scan | less

The pipe "|" sends the output to the following program, "less", which then lets you read one screen at a time. You can control "less" with the up and down arrows, page up and down, you can search with the "/" command, and quit with q.

Several lines down in the output from that command, you should see a line that looks like:


Where "yourWiFI" is your WiFi network name (the SSID, the same name you use when connecting a device to the network). If you have more than one WiFi network in the area, the output will show a similar block for each network (generally a couple dozen lines of info for each WiFi network).

If you do see your WiFi's SSID, a couple of lines above that you should see a line that starts with "Quality...". It looks something like this:
Quality=43/70 Signal level=-67 dBm
This shows numbers relating to the quality of the connection and the signal strength. These numbers can be useful when troubleshooting a noisy or weak signal (repositioning the Pi in relation to the Wifi access point can often help improve the signal).

Some real- world examples:

  • Quality=43/70 Signal level=-67 dBm I was able to connect reliably, but turning on a florescent light in the area sometimes caused problems.
  • Quality=20/70 Signal level=-82 dBm user was not able to SSH via WiFi
  • Quality=70/70 Signal level=-29 dBm. user reported solid connection

If you do not see your network listed in the output, then the Pi is simply not seeing the the network at all. There could be a number of causes. See some of these further up: WiFi Signal Strength, Hidden SSID, Weak/Inadequate Power Supply, Electrical Interference.

:thinking: Still not working?

Please use the OctoPi WiFi/network connection troubleshooting megatopic to seek help!

Note: This first post in this topic is a wiki, so others can edit and add to it. If you do edit this post, please try to follow the formatting here to help separate the various various issues (I just copy the heading line from an existing section, paste it in, and edit to make a new one). Don't let formatting fears stop you from posting a fix that may be helpful to others. I'll try to stop in and clean things up from time to time if it's needed. When editing, please leave this paragraph at the bottom of the page.


I'm wondering if it might make sense to move this into the FAQ category? What do you think?


Makes sense to me.

I'm hoping others will jump in with other common issues. I also have a few diagnostic commands I have recommended in the past, but I never remember the exact format. I'll put them up when I get a chance.

UPDATE: diagnostic commands added in this post

1 Like

Sounds good! I've moved it over now.

1 Like

7 posts were split to a new topic: OctoPi wifi/network connection troubleshooting megatopic

(This post has now been merged into the top post)


@John_Mc I've taken the liberty to move the contents of your "diagnostics" post into the top post as well - will hopefully get more people to see it.

1 Like

Good idea. I was thinking of removing the original diagnostics post, now that it's in the first post, but I'm thinking it has been linked to from other posts here and from other sites, so I guess I'll leave it alone.

We can just edit it down to

(This post has now been merged into the top post)

or something?

Makes sense to me. That way, we don;t have to edit it in two places if there is an update.

I'll give it a try. Hopefully I don't screw things up in the process.

Oops! I guess I can no longer edit that post (no little pencil icon showing up in the menu choices.)

Ah, probably time limited then. I've taken care of it, no problem!

edit yup, there was a time limit of 60 days. Since we have public edit diffs anyhow, I've now disabled that time limit. If this causes issues down the road we can always re-enable it.

Just wanted to drop a tip. Configuring WiFi country is outlined in when talking about editing the txt file in the boot folder, but is kind of glossed over when talking about configuring with keyboard+mouse+monitor. I've never had good luck getting my card reader to work with partitioned SD cards, so I always just plug a monitor in to my Pi's. This is my first board newer than a 3B, and I had no idea about having to configure wifi country. I was pulling my hair out trying to figure it out. While sudo raspi-config'ing, wifi country is in the localization options.

Actually, I'd forgotten to do the editing before booting on your RasPi of choice. Editing it after burning the .img file works.

Trying to edit them on a "live machine" doesn't. Something about editing the file to set a static IP fails to be written/read correctly.

for me it was a "duh" ....

I had this same problems as OP and many people who were in this thread. I fixed my problem by doing this:

  1. I logged into my modem ( for me)
  2. I went to advanced -> DHCP Reservation List
  3. I found the ip address that my pi states when it starts up (by hooking up a monitor to my pi)
  4. I removed that ip address from the DHCP Reservation List by clicking remove next to that IP address
  5. I ran ----> sudo reboot now <------ on the pi to reboot it, when it rebooted, i could connect to it now

that worked for me, hope it does for someone else also

I am a new user of 3D printing and Raspberry Pi's. I set up OctoPi 0.17 on a new RPi 4 (4mb) at my home location. I have a very robust internet connection (1 Gbps) there and octopi was quickly recognized on my network and I was able to use it with my 3D printer and web cam with no trouble. I have since moved the printer to another location with a different network and modified the octopi-wpa-supplicant.txt with the new network data using Notepad 3. The pi booted up but the new network has not been able to see the pi (octopi). I tried moving the pi to different locations including right next to the router but the network still does not see it. I even connected the pi directly to the modem/router with ethernet - same results. I have used Angry IP Scanner and have accessed the router configuration files but the network does not see the pi. I have tried everything I know after reading the above posts. I even started fresh with a new micro SD card (good quality Samsung) and a new octopi image but I still cannot get my network to see the pi. I added the line for hidden SSID just for grins but no change. This new network is admittedly not as robust as the original one but it is stable and I can see and operate other devices on it (cameras, security system, etc). I use PuTTY so I do not know how to SSH into this pi without an IP address. I am wondering if I have a hardware problem? Is there something else I am missing?

UPDATE: I just tried to connect to this new network (see post above) with a different raspberry that has the standard Raspberry OS loaded on it. It did so with no problem. I can connect to the network and this pi is recognized as raspberry.local in the IP listing of Angry IP Scanner. So I am back to wondering what could be wrong with my pi that has octopi OS. Is this a hardware issue or am I doing something wrong in my octopi setup?

1 Like

I guess I'm still looking for help. I do not think I have a connectivity problem but the network does not see my pi when I am using Octopi as the OS. What could be wrong? Any help would be appreciated. Or am I asking in the wrong place?

I f you need help, you may open a new thread in the section Get Help - Networking. This is the FAQ section.
When opening the thread, please share as much information as required in the template as possible.

If you do start a topic in the Get Help - Networking section, please include the response you get to the commands listed near the end of the first post here:

ifconfig wlan0


sudo iwlist wlan0 scan

These will help folks zero in on the problem.