'ModuleNotFoundError' in Thonny - what it is and how to fix it

I have been learning Python since the end of last year, and recently moved from IDLE to Thonny. I was surprised to almost immediately hit a 'ModuleNotFoundError' in Thonny - here's why, and how to fix it.

IDLE is the Integrated Development Environment (or IDE) that comes bundled with the default implementation of Python, so I am sure that many new Pythonistas begin their Python journey using IDLE. I certainly did.

IDLE has the benefit of simplicity, but is perhaps best suited to absolute beginners. After a while I was ready to move to a different IDE and chose Thonny: still simple, still free, but with some useful features for learners such as the ability to debug step by step without adding breakpoints first.

However when I tried to run many of my Python scripts in Thonny I received a 'ModuleNotFoundError' like this:

And it wasn't just pandas: none of the packages I had been using with IDLE, from seaborn to matplotlib, were available in Thonny! Running a script that required any of them threw a similar 'ModuleNotFoundError'. I'd installed these packages using pip (not via IDLE) so had assumed they would all be available for use in any IDE, Thonny included.

The reason for this confusion is that Thonny comes with Python 3.7 built in (or 'bundled'), and by default uses this Python installation rather than the one you may have previously been using with a different IDE. If you look at the first line of the screengrab above, you can see that Thonny is telling me that I am using "Python 3.7.7 (bundled)". For reference it is located at:
C:\Users\username\AppData\Local\Programs\Thonny\python.exe

You will also see this Python installation referred to in Thonny's menus as "the same interpreter which runs Thonny".

If Thonny is your first experience of Python, then I suppose that bundling Python with Thonny removes the need to install Python separately and eliminates one barrier to entry - a good thing. However if you are moving to Thonny from a different IDE then it can be quite disconcerting!

If you find yourself in this situation, there are two things you can do. Perhaps the easier approach is to swap back to your previous Python interpreter (installation) - or you could install your required packages for use with Thonny's bundled interpreter. Here's how to do either:

Changing Python interpreter in Thonny

1. In Thonny's menu, go to Run > Select interpreter
2. In the 'Which interpreter or device should Thonny use for running your code?' dropdown, select Alternative Python 3 intepreter or virtual environment
3. If yours isn't already in the list of 'known interpreters', select Locate another python.exe and navigate to your Python executable. Unless you've installed it somewhere unusual, it's likely to be something like the following:
   C:\Users\username\AppData\Local\Programs\Python\Python38\python.exe
4. Click OK
5. Now let's check that has done the trick. In Thonny's menu, go to Tools > Manage packages...
6. Thonny's package manager will show you all installed packages in the panel on the left. Hopefully you will see everything you are expecting!
7. Incidentally you can click on any package to see metadata such as version number, summary and author/s, and dependencies:

For example here you can see that pandas requires numpy among other packages, and that I don't have the latest stable version of pandas installed.

Installing packages for Thonny's default interpreter

1. In Thonny's menu, go to Run > Interpreter
2. In the 'Which interpreter or device should Thonny use for running your code?' dropdown, make sure The same interpreter which runs Thonny (default) is selected
3. Hit OK
4. In Thonny's menu, go to Thonny's package manager (Tools > Manage packages)
5. Some packages will already be installed, eg the Python imaging library 'pillow' - you will see these listed in the pane on the left. However if you have previously installed packages such as matplotlib, pandas and numpy for use in IDLE or a different IDE, then they are likely to be missing from this list and will need to be installed for use with Thonny's default interpreter.
6. Type your package name in the search field at the top (eg matplotlib) - you need the exact package name. If in doubt, check the Python Package Index at pypi.org
7. Click Find package from PyPI
8. Click Install
9. Depending on the size of the package, the installation can take a little while - so wait until you get a success message and/or the popup disappears
10. Once you have installed all the missing packages, click Close. They will be available for use immediately.

Although initially confusing, the approach that Thonny takes is pretty powerful. It enables you to set up and very quickly swap between multiple Python interpreters, and see at a glance which packages have been installed for use with each. This could help you, for example, avoid dependency conflicts.