Skip to main content

How to Resolve "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.

note

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 (or pip3.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 only
    note

    Using a virtual environment (explained below) is the best way to avoid permission issues.

  • python -m pip: If pip isn't directly in your PATH, use this:

    python -m pip install pyserial  # Or python3 -m pip, py -m pip
    note

    This 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.

  1. Create: python3 -m venv venv (or python -m venv venv, py -m venv venv)
  2. 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
  3. Install: pip install pyserial (inside the activated environment).

Your terminal prompt should change (e.g., (venv) $).

Multiple Python Versions:​

  • Check: python --version (or python3 --version)
  • Correct pip: Use the pip 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
note

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 (or py -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.

Table of Contents