Skip to main content

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

The error ModuleNotFoundError: No module named 'pymysql' in Python means the pymysql library, which is used to connect to MySQL databases, isn't installed in the Python environment you're using, or it's installed incorrectly.

This guide provides clear steps to resolve this error, covering installation, virtual environments, IDE configurations, and troubleshooting.

Understanding the Error​

The ModuleNotFoundError occurs because your Python code tries to import pymysql, but the interpreter can't find the pymysql package. This is almost always a simple installation or environment issue.

Installing pymysql​

The standard and recommended way to install pymysql is using pip:

pip install pymysql
# OR, for Python 3 (might be pip3, pip3.10, etc. on your system)
pip3 install pymysql

# OR, if pip is not in your PATH:
python -m pip install pymysql
python3 -m pip install pymysql

# OR, Windows 'py' launcher:
py -m pip install pymysql

Choose the command that works for your system. The python -m pip form is generally the most reliable.

Troubleshooting ModuleNotFoundError​

If you still get the error after installation, follow these steps:

Verify Installation​

Confirm that pymysql is installed in the correct environment. Activate your virtual environment (if you're using one), and then run:

pip show pymysql
# OR
python -m pip show pymysql

This will show you information about the installed package, including its location. If it says "Package(s) not found", the installation didn't work, or you're in the wrong environment.

Look at the Location: field in the output. It should point to your virtual environment's site-packages directory (if you're using one), not a system-wide location.

Virtual Environments (Essential!)​

Always use virtual environments for your Python projects. This isolates project dependencies and prevents conflicts.

  1. Create a virtual environment:

    python3 -m venv venv  # Recommended: Use the built-in 'venv' module
    # OR (if the above fails)
    python -m venv venv
    # OR (Windows)
    py -m venv venv

  2. Activate the environment:

    • Linux/macOS (bash/zsh):

      source venv/bin/activate

    • Windows (Command Prompt):

      venv\Scripts\activate.bat

    • Windows (PowerShell):

      venv\Scripts\Activate.ps1

      If you get a "running scripts is disabled" error in PowerShell, run this command once (as an administrator, if necessary) and then try activating again:

      Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

  3. Install pymysql inside the activated environment:

    pip install pymysql

IDE Interpreter (VS Code, PyCharm)​

If you're using an IDE, ensure it's using the correct Python interpreter:

  • VS Code: Use the Python: Select Interpreter command from the Command Palette (Ctrl+Shift+P or Cmd+Shift+P). Choose the interpreter associated with your virtual environment (if any) or the correct system-wide Python installation.

  • PyCharm: Go to File > Settings > Project > Python Interpreter (or PyCharm > Preferences > Project > Python Interpreter on macOS). Select the correct interpreter.

Naming Conflicts (Shadowing)​

Make absolutely sure you don't have a file or directory named pymysql.py (or pymysql) in your project directory or anywhere else on your PYTHONPATH. This will "shadow" the installed pymysql package. Rename your file if this is the case.

Restarting the Kernel/IDE​

Sometimes, especially with Jupyter Notebooks or IDEs, a restart of the Python kernel or the entire IDE is necessary for changes to be recognized.

Installation in Specific Environments​

Anaconda​

conda install -c anaconda pymysql
  • Anaconda has its own package manager, and you should use it to install packages in your anaconda environments.

Jupyter Notebook​

!pip install pymysql

Basic Usage Example​

Here's a minimal example of how to use pymysql to connect to a MySQL database (replace the placeholders with your actual credentials):

import pymysql.cursors

# Connect to the database
connection = pymysql.connect(host='localhost',
                             user='your_username',
                             password='your_password',
                             database='your_database',
                             charset='utf8mb4',
                             cursorclass=pymysql.cursors.DictCursor)

try:
    with connection.cursor() as cursor:
        # Read a single record
        sql = "SELECT `id`, `password` FROM `users` WHERE `email`=%s"
        cursor.execute(sql, ('[email protected]',))
        result = cursor.fetchone()
        print(result)
finally:  # Always close the connection
    connection.close()
  • Make sure that you are using your own host, username, password and database.

Conclusion​

The ModuleNotFoundError: No module named 'pymysql' error almost always stems from an installation or environment issue.

By following these steps (installing with pip, verifying the installation, ensuring you're using the correct environment/interpreter, and checking for naming conflicts) you can resolve the error and connect to your MySQL database using pymysql.

  • Always use virtual environments to manage project dependencies.
  • If you're still having trouble, double-check that you've activated the correct virtual environment and that your IDE is pointing to the correct Python interpreter within that environment.

Table of Contents