How to fix ModuleNotFoundError: No module named '...'

This article shows steps to fix the error ModuleNotFoundError: No module named '...'. The error means Python cannot find a package or file you try to use. Many new and even experienced coders see this error. It is a top question online right now because people move to new Python versions, use virtual environments, or share code across machines.

Quick answer

If you see ModuleNotFoundError, first check you installed the package for the same Python you run. Use python -m pip install packagename (or py -m pip install packagename on Windows). If you use a virtual environment, activate it before you run your code. These checks fix most problems.

Step-by-step solution

1. Find the Python that runs your code.
   Open a terminal and run:

   python --version
   
   python -c "import sys; print(sys.executable)"

   This shows the exact Python program. If this is not the one you expect, later installs may go to a different place.
2. Install with that Python.
   Run:

   python -m pip install packagename

   Using -m pip makes pip run inside that same Python. This avoids mixing system pip and a different Python.
3. Use a virtual environment for each project.
   Make a clean venv:

   python -m venv venv
   
   source venv/bin/activate   # macOS/Linux
   venv\Scripts\activate      # Windows

   Then install packages while the venv is active. This keeps project packages separate and reduces conflicts.
4. Check your file and folder names.
   If your file is named requests.py or a folder is named json, Python may import that file instead of the real package. Rename your file and remove any __pycache__ folders, then try again.
5. Print sys.path to see import paths.
   In a short script:

   import sys
   
   print(sys.executable)
   for p in sys.path:
   print(p)

   Python looks in these places for modules. If your code or package folder is not listed, Python cannot import it.
6. Reinstall or update the package.
   Sometimes an install was partial. Run:

   python -m pip uninstall packagename
   
   python -m pip install packagename

   On some systems use --user or use a venv to avoid admin rights issues.
7. Check version and system requirements.
   Some packages need a certain Python version or extra system libraries (like libxml2). Read the package page on PyPI or its docs and install any needed OS libraries, then reinstall the Python package.
8. Try a fresh environment if all else fails.
   Make a new virtual env and only add the packages you need. This clears hidden conflicts from many installs and shows if the problem is in your project or your machine.

Example common cases (simple)

• Installed but import fails: You did pip install requests but import requests fails. Fix: run python -m pip install requests for the Python you use, or activate your venv first.
• File name clash: Your script is myapp/requests.py and import requests fails. Fix: rename requests.py to my_requests.py and delete __pycache__.
• Windows with both py and python: Use py -m pip install packagename to be safe.

Troubleshooting and extra tips

• Use python -m pip --version to check which pip belongs to which Python.
• If your IDE runs a different interpreter, change the IDE setting to the right Python (PyCharm, VS Code let you pick the interpreter).
• Clear caches: remove __pycache__ folders and restart your Python shell or IDE.
• If you build packages from source, use wheels when possible. Wheels install faster and fail less than building from source.
• On Linux, avoid sudo pip install. Use distro packages, --user, or a venv. System-wide pip installs can break the system Python.

Useful Sources

Read more at the official docs and helpful guides:

• Python docs — The import system
• pip documentation — Getting started

Who this helps

This guide helps learners, students, and developers who get stuck when code moves to a new machine or when they try a new Python version.

FAQ

Is ModuleNotFoundError the same as ImportError?

Answer: ModuleNotFoundError is a kind of ImportError. It means Python did not find the module you asked for.

Why can I import locally but not on a server?

Answer: The server may use a different Python or not have the package installed. Repeat the install steps on the server and use a venv.

Can wrong file names cause this error?

Answer: Yes. A local file that shares a package name can hide the real package. Rename it and clear caches.

I followed all steps. What now?

Answer: Copy sys.executable and sys.path output and ask on a help site or include them in an issue. That information helps others find the cause.

More tips and tools (easy)

• See installed packages:

  python -m pip list

  This shows the exact package names and versions.
• Find where a package is installed:

  python -m pip show requests

  Look for Location: in the output. That folder should be on sys.path.
• Editable installs for local packages:

  python -m pip install -e .

  This makes your package importable while you edit its files.
• Conda users: If you use conda, install with conda install packagename or use pip inside the conda env. Make sure the conda env is active.
• Windows common fix: Use py -m pip install packagename to pick the right Python. Use where python to see which Python is on your PATH.
• When a package uses native code: Some packages need compiled extensions (Visual C++ build tools on Windows, build-essential on Linux). If wheel build fails, read the package docs for system steps.

Real world example (step-through)

1. I run python3 main.py and see ModuleNotFoundError: No module named 'foo'.
2. I run python3 -m pip list and foo is not on the list.
3. I run python3 -m pip install foo. Install finishes.
4. I run python3 main.py again and now import foo works.

This exact flow fixes many cases. If install fails, check the pip output for missing system packages. If install succeeds but import fails, check file names and sys.path.

Final checklist (short)

• Did you run python -m pip install packagename?
• Is your virtual env active?
• Are you using the same Python in your IDE and terminal?
• Is your script or folder name clashing with the package name?
• Did you restart your shell or IDE after changes?

If yes and it still fails, gather sys.executable, sys.path, and pip show packagename, then ask for help with that info.

Conclusion

ModuleNotFoundError is common and fixable. Most times you just need to install the package into the right Python or use a virtual env. If you follow the steps above, you will solve most cases. Keep notes on which Python and pip you use — it will save time later. Happy coding!