How to Solve "ModuleNotFoundError: No module named 'serial'" in Python
The error ModuleNotFoundError: No module named 'serial'
in Python means that the pyserial
library, which is used for serial communication, is not installed in your current Python environment.
Importantly, the module name you import
is serial
, but the package name you install with pip
is pyserial
.
This guide explains how to install pyserial
, troubleshoot common installation problems, and configure different development environments (VS Code, PyCharm, Jupyter, Anaconda).
Installing pyserial
(The Basic Solution)
The correct package name to install is pyserial
, not serial
. Use pip
:
pip install pyserial
-
Multiple Python Versions: If needed, use
pip3
(orpip3.9
, etc.):pip3 install pyserial
-
Permissions Errors: If you get a permission error:
sudo pip3 install pyserial # Linux/macOS (Use with caution!)
pip install pyserial --user # Install for the current user onlynoteUsing a virtual environment (explained below) is the best way to avoid permission issues.
-
python -m pip
: Ifpip
isn't directly in yourPATH
, use this:python -m pip install pyserial # Or python3 -m pip, py -m pip
noteThis is the most robust and recommended way to use pip.
-
Conda: If you are using Anaconda, install
pyserial
with the following command:
conda install -c anaconda pyserial
Verifying the Installation
After installing, verify that pyserial
is accessible:
import serial
print(serial.__version__) # Print the pyserial version
If this script runs without a ModuleNotFoundError
, pyserial
is installed correctly. If you still get the error, move to the troubleshooting steps.
Troubleshooting ModuleNotFoundError
Virtual Environments (Essential)
Always use virtual environments. They isolate dependencies and prevent conflicts.
- Create:
python3 -m venv venv
(orpython -m venv venv
,py -m venv venv
) - Activate:
- Linux/macOS:
source venv/bin/activate
- Windows (cmd):
venv\Scripts\activate.bat
- Windows (PowerShell):
venv\Scripts\Activate.ps1
- If powershell throws an error, run the command:
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
- If powershell throws an error, run the command:
- Linux/macOS:
- Install:
pip install pyserial
(inside the activated environment).
Your terminal prompt should change (e.g., (venv) $
).
Multiple Python Versions:
- Check:
python --version
(orpython3 --version
) - Correct
pip
: Use thepip
that corresponds to your intended Python version.
IDE Configuration (VS Code, PyCharm)
Configure your IDE to use the correct interpreter/environment.
Jupyter Notebook
Install within a notebook cell using:
!pip install pyserial
Ensure your Jupyter kernel uses the correct environment.
Naming Conflicts
Never name your files serial.py
.
Reinstalling pyserial
pip uninstall pyserial
pip install pyserial
Installation Instructions for Specific Environments
Windows:
- Open Command Prompt or PowerShell.
- Use
pip install pyserial
(orpy -m pip install pyserial
).
macOS / Linux:
- Open your Terminal
- Use
pip3 install pyserial
Anaconda:
- Use
conda install -c anaconda pyserial
Jupyter Notebook (within a cell):
!pip install pyserial
Handling "Import 'serial' could not be resolved" (Pylance - VS Code)
- Select correct interpreter in VS Code.
- Restart VS Code.
- You can disable the warning by adding
# type: ignore
next to the import statement:import serial # type: ignore
Conclusion
The ModuleNotFoundError: No module named 'serial'
error is almost always resolved by installing the pyserial
package using pip
within the correct Python environment.
Using virtual environments is critical for managing dependencies and preventing these errors.
This guide provided a complete walkthrough of installation, troubleshooting, and environment-specific instructions to get you working with serial communication in Python.