Fix ModuleNotFoundError: No Module Named 'pymysql'

Seeing the error ModuleNotFoundError: No module named 'pymysql' is common for Python beginners. This error stops your code from using the PyMySQL library. It usually means Python cannot find the installed package.

This guide explains why this error happens and how to fix it. You will learn simple steps to install PyMySQL correctly. We also show example code and outputs to help you understand the solution.

What Causes the Error?

The ModuleNotFoundError occurs when Python tries to import a module that is not available in your environment. PyMySQL is a third-party library. You must install it separately using pip (Python's package manager).

Common reasons include:

• PyMySQL is not installed at all.
• You installed it for a different Python version (e.g., Python 2 vs Python 3).
• You are working in a virtual environment where PyMySQL is missing.
• Your script's filename conflicts with the module name.

If you encounter similar errors with other modules, check our guide on How To Solve ModuleNotFoundError: No module named in Python for general troubleshooting.

How to Install PyMySQL

The most common fix is installing PyMySQL via pip. Open your terminal or command prompt and run:

pip install pymysql

If you use Python 3 specifically, try:

pip3 install pymysql

After installation, verify it worked by importing the module in a Python shell:

# Check if pymysql is installed
import pymysql
print("PyMySQL imported successfully!")

Expected output:

PyMySQL imported successfully!

If you see the output above, the installation succeeded. If the error persists, read the next sections.

Using a Virtual Environment

Virtual environments isolate your project's dependencies. If you use one, you must install PyMySQL inside that environment. First, activate your virtual environment:

On Windows:

venv\Scripts\activate

On macOS/Linux:

source venv/bin/activate

Then install PyMySQL:

pip install pymysql

This ensures the library is available only for your project. For more details on environment issues, see the article on How To Solve ModuleNotFoundError: No module named in Python.

Check Your Python Version

Sometimes you install PyMySQL for Python 2 but run your script with Python 3, or vice versa. Check your Python version first:

python --version

Then install PyMySQL for that version. For example, if you use Python 3.9:

python3.9 -m pip install pymysql

This ensures the package matches your interpreter. If you still face issues, the problem might be a naming conflict.

Avoid Naming Conflicts

Never name your Python script pymysql.py. If you do, Python will try to import your script instead of the real library. Rename your file to something else, like database.py.

Example of a bad script name that causes the error:

# File named pymysql.py (WRONG)
import pymysql  # This imports your own file, not the library

Fix: Rename the file and delete any .pyc cache files if needed.

Example: Connecting to MySQL with PyMySQL

Once installed, you can use PyMySQL to connect to a MySQL database. Here is a simple example:

import pymysql

# Database configuration
config = {
    'host': 'localhost',
    'user': 'root',
    'password': 'your_password',
    'database': 'test_db'
}

try:
    # Establish connection
    connection = pymysql.connect(**config)
    print("Connected to MySQL database successfully!")

    # Create a cursor object
    cursor = connection.cursor()
    cursor.execute("SELECT VERSION()")
    version = cursor.fetchone()
    print(f"MySQL version: {version[0]}")

    # Close connection
    cursor.close()
    connection.close()

except pymysql.Error as e:
    print(f"Error connecting to database: {e}")

Expected output (if database exists):

Connected to MySQL database successfully!
MySQL version: 8.0.32

This code shows how to use pymysql.connect() to connect and run a simple query. Make sure your MySQL server is running before testing.

Using pip List to Verify

To see all installed packages, run:

pip list

Look for pymysql in the output. If it's missing, reinstall it. If it's there but the error persists, check your Python path.

Check Python Path

Sometimes Python cannot find the installed package because of path issues. Print your sys.path to see where Python looks for modules:

import sys
print(sys.path)

Ensure the path to your site-packages directory is included. If not, you may need to reinstall Python or adjust your environment variables.

For more tips on resolving import errors, refer to the guide on How To Solve ModuleNotFoundError: No module named in Python.

Conclusion

The ModuleNotFoundError: No module named 'pymysql' is easy to fix. Always install the library using pip install pymysql in the correct environment. Check your Python version, avoid naming conflicts, and verify your virtual environment if you use one.

With these steps, you can connect to MySQL databases smoothly. Practice with the example code to build confidence. Happy coding!