ModuleNotFoundError: No module named 'fbs_runtime'

If you're following an fbs tutorial and trying to run your main.py file from an IDE like Spyder, you might run into this error:

ModuleNotFoundError: No module named 'fbs_runtime'

Why this happens

The fbs_runtime module is part of the fbs package. When you create and run an fbs project using the fbs run command on the terminal, fbs sets everything up so that fbs_runtime is available to your script automatically.

However, if you open the main.py file directly in an IDE like Spyder and hit "Run" or "Debug," the IDE uses its own Python environment. Unless fbs is installed in that environment, Python won't be able to find fbs_runtime and you'll get the ModuleNotFoundError.

How to fix it

There are two ways to solve this, depending on how you prefer to work.

Option 1: Run your project using fbs run

The simplest approach is to run your fbs project the way it's designed to be run — from the command line using:

fbs run

Make sure you run this from the root of your fbs project directory (the folder that contains the src folder). This command handles all the environment setup for you.

Option 2: Install fbs in your IDE's Python environment

If you'd rather run and debug directly from Spyder (or another IDE), you need to install the fbs package into the Python environment that your IDE is using. You can do this with pip:

pip install fbs

To make sure you're installing into the correct environment, check which Python interpreter Spyder is using. In Spyder, go to Tools → Preferences → Python interpreter and note the path. Then use that specific Python to install fbs:

/path/to/your/python -m pip install fbs

After installing, restart Spyder and try running your script again. The fbs_runtime module should now be found without any issues.

A note on virtual environments

If you set up your fbs project inside a virtual environment (which is recommended), make sure your IDE is configured to use that same virtual environment as its interpreter. Mixing environments is one of the most common causes of ModuleNotFoundError in Python — the package is installed in one place, but your IDE is looking in another.

In Spyder, you can point the interpreter to your virtual environment's Python executable through Tools → Preferences → Python interpreter → Use the following Python interpreter, and then browse to the python binary inside your virtual environment's bin (or Scripts on Windows) folder.

Once your IDE and your project are using the same environment, import errors like this go away.