ModuleNotFoundError when working with FastAPI in Python

David Y.

—February 15, 2024

The Problem

When working on my FastAPI project, I sometimes encounter the following ModuleNotFoundError errors:

1. ModuleNotFoundError: No module named 'fastapi'
2. ModuleNotFoundError: No module named 'httpx'

I’m pretty sure I’ve installed both of these packages, and the errors are intermittent. How can I resolve these errors and ensure my FastAPI project runs consistently?

The Solution

ModuleNotFoundError errors often relate to issues with Python environment configuration. The best way to solve these issues and ensure that our project runs consistently on different systems is to create a virtual environment and use that environment every time we run the code in our project. In fact, the ModuleNotFoundError you’ve encountered may stem from switching between running the project in a virtual environment and running the project directly on your system.

First, you’ll need to check whether your project has a virtual environment configured already. If your project directory contains a directory named something like env or venv, and that folder contains directories with names like bin, include, and lib, then you have a virtual environment already. Otherwise, you will need to create one.

If you don’t have a virtual environment set up, create one by running this command in your project’s root directory:

python -m venv venv

This will create a new virtual environment in the directory venv. To activate your environment, whether it’s a pre-existing one or the one we just created, run this command:

source venv/bin/activate

Once you’ve run this command, you should see the environment name (venv, in most cases) appear somewhere in your terminal prompt. This means that you’ve successfully activated the environment and all commands you run will be run in the context of this environment. Every time you work on your FastAPI project, you must remember to activate the environment before attempting to run anything. Note that you will need to ensure the environment is active in every terminal window and program you use to work with your project.

Inside your environment, run the following command to install your relevant packages:

pip install fastapi httpx

If your project has any other Python dependencies, you should install those too, even if you’ve already installed them outside of this virtual environment. Then, without leaving the environment, run your project again. The ModuleNotFoundError errors should no longer be present.

It’s a good idea to maintain a requirements.txt file for your project so that it can be easily set up on different systems. Virtual environments make it easier for us to do this because we can assume that all of the packages installed in a virtual environment are dependencies for the current project. So instead of having to create a requirements.txt file manually, we can do it like this:

pip freeze > requirements.txt

The pip freeze command outputs a list of all installed packages in the format required for a requirements.txt file. Outside of our virtual environment, this would create a requirements file with every single Python package we’ve ever installed, but here it will be limited to just the packages installed in our virtual environment.

If you would prefer not to use a virtual environment, please refer to this answer about troubleshooting ModuleNotFound errors without using virtual environments.