Skip to main content

How to Solve "ModuleNotFoundError: No module named 'PyQt5'" in Python

The ModuleNotFoundError: No module named 'PyQt5' error in Python indicates that the PyQt5 library, used for creating graphical user interfaces (GUIs), is not installed in your current Python environment, or Python can not find it.

This guide provides step-by-step instructions to install PyQt5, troubleshoot common installation problems, and configure your IDE (VS Code, PyCharm) and Jupyter Notebook.

Installing PyQt5 (The Basic Solution)

The standard way to install PyQt5 is using pip, Python's package installer. Open your terminal (or command prompt) and run:

pip install pyqt5
  • Multiple Python Versions: If you have multiple Python versions, you may need to use pip3 (or a more specific version like pip3.9):

    pip3 install pyqt5
  • Permissions Errors: If you encounter permissions errors on Linux/macOS, try using sudo (use with caution):

    sudo pip3 install pyqt5  # Use with caution!

    Or, preferably, install into a user location:

     pip install pyqt5 --user
    pip3 install pyqt5 --user

    Using virtual environments (explained below) is the best way to avoid permission problems.

  • python -m pip: If pip isn't working directly, try:

    python -m pip install pyqt5  # Or python3 -m pip

    This makes sure you're using the pip associated with your current Python.

  • Conda: If you use anaconda, run the following command to install PyQt5:

    conda install -c anaconda pyqt

Verifying the Installation

After installing, verify that PyQt5 is accessible by running a simple Python script:

from PyQt5.QtCore import QObject, pyqtSignal  # Import something from PyQt5

class Foo(QObject): # Basic class using PyQt5
closed = pyqtSignal()
range_changed = pyqtSignal(int, int, name='rangeChanged')
valueChanged = pyqtSignal([int], ['QString'])

print("PyQt5 installed successfully!") # If no error, it's good
  • The code imports the PyQt5 and creates a basic class to verify that it can be properly imported.

If this script runs without a ModuleNotFoundError, PyQt5 is installed correctly. If you still get the error, proceed to troubleshooting.

Troubleshooting ModuleNotFoundError

Virtual Environments (Essential)

Always use virtual environments. They prevent conflicts between projects.

  1. Create (if needed):

    python3 -m venv venv  # Or python -m venv venv, or py -m venv venv
  2. Activate:

    • Linux/macOS: source venv/bin/activate
    • Windows (cmd.exe): venv\Scripts\activate.bat
    • Windows (PowerShell): venv\Scripts\Activate.ps1
      • If you receive error message that .ps1 file can not be loaded, use this command and rerun activation command:
        Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
  3. Install: pip install pyqt5 (inside the activated environment).

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

Multiple Python Versions:

  • Check: python --version (or python3 --version)
  • Correct pip: Use the pip (pip3, pip3.x, python -m pip) corresponding to the Python version you're using.

IDE Configuration (VS Code, PyCharm)

Your IDE must use the correct interpreter/environment.

  • VS Code:

    1. Command Palette (Ctrl+Shift+P / Cmd+Shift+P).
    2. "Python: Select Interpreter".
    3. Choose the correct environment (often with venv in the name).
  • PyCharm:

    1. "File" -> "Settings" -> "Project" -> "Python Interpreter".
    2. Select/add the correct interpreter.

Jupyter Notebook

In a Jupyter Notebook cell, install with:

!pip install pyqt5

Important: This installs into Jupyter's environment, which might not be your project's environment. Ensure your Jupyter kernel uses the right environment.

Naming Conflicts

Never name your files or directories pyqt5.py or pyqt5. This will cause Python to try to import your file instead of the library. Rename your file.

Reinstalling PyQt5

As a last resort:

pip uninstall pyqt5
pip install pyqt5

Installation Instructions for Specific Environments

Windows:

  • Open Command Prompt or PowerShell.
  • Use pip install pyqt5 (or py -m pip install pyqt5).

macOS / Linux:

  • Open your Terminal
  • Use pip3 install pyqt5

Anaconda:

  • Use conda install -c anaconda pyqt

Jupyter Notebook (within a cell):

!pip install pyqt5

Handling "Import 'PyQt5' could not be resolved from source Pylance" (VS Code)

  • Check the selected interpreter and make sure that the correct interpreter is used.
  • Restart VS Code.
  • Disable Pylance and enable it again.
  • Ignore the error by adding # type: ignore next to the import statement:
    from PyQt5.QtCore import QObject, pyqtSignal # type: ignore
note

This will not fix the error, but it will disable the warning.

Conclusion

The ModuleNotFoundError: No module named 'PyQt5' is almost always caused by installation problems.

By carefully following the installation steps:

  • using virtual environments
  • verifying your IDE/Jupyter configuration

you can quickly resolve the issue and start building GUI applications with PyQt5.