How to Resolve "ModuleNotFoundError: No module named 'pyautogui'" in Python

Fix the 'ModuleNotFoundError: No module named pyautogui' error by installing the library correctly in your Python environment, troubleshooting virtual environments, and resolving IDE-specific issues.

The ModuleNotFoundError: No module named 'pyautogui' is a frequent error encountered by Python users working with GUI automation. It signals that the Python interpreter can not locate the pyautogui library when your script attempts to import it. This typically means the package isn't installed in the Python environment you're currently using.

This guide provides clear, step-by-step solutions to install pyautogui correctly and resolve the error.

Understanding the Error

This error means Python searched its standard locations for installed packages and couldn't find the pyautogui library required by your import pyautogui statement.

Solution 1: Install `pyautogui` using `pip` (Most Common)

pyautogui is a third-party library and needs to be installed using pip, Python's package installer.

Open your terminal or command prompt and run:

pip install pyautogui

Variations (Choose the one appropriate for your setup):

pip3 install pyautogui

python -m pip install pyautogui
python3 -m pip install pyautogui

py -m pip install pyautogui

Troubleshooting Common Installation Problems:

If pip install pyautogui gives an error or the ModuleNotFoundError persists, check these common issues:

Using the Correct pip: Ensure you're using the pip linked to the Python interpreter running your script (usually pip3 or python3 -m pip for Python 3). Check versions: python --version, pip --version (or pip3 --version).
Working with Virtual Environments (Crucial!): This is the most frequent reason for the error. You likely installed pyautogui globally but are running your script within a virtual environment (or vice-versa).
- Activate your virtual environment before installing:
```
python3 -m venv venv
source venv/bin/activate        # Linux/macOS
.\venv\Scripts\Activate.ps1     # Windows PowerShell
.\venv\Scripts\activate.bat     # Windows CMD
pip install pyautogui
```
- Confirm your IDE (VS Code, PyCharm) is using the Python interpreter from your activated virtual environment.
Permissions Issues (--user or sudo): If installing globally (not recommended).
- Recommended: Install for the current user: pip install pyautogui --user
- Use Cautiously: Use admin/root privileges: sudo pip install pyautogui (Linux/macOS) or Run Terminal as Administrator (Windows). Virtual environments avoid this.
Multiple Python Installations / IDE Configuration: Verify the Python interpreter selected in your IDE matches the one you used pip with. Use the "Select Interpreter" command in your IDE.
Naming Conflicts (pyautogui.py): Ensure none of your project files are named pyautogui.py. This "shadows" the installed package. Rename your file if necessary. Avoid using pyautogui as a variable name before the import.

Verifying Installation (`pip show`)

Confirm the package is installed in the active environment:

pip show pyautogui

This command should display package details (Name, Version, Location, etc.). "Package(s) not found" means it's not installed in that environment.

Platform/Tool Specific Installation Notes:

Windows: Use CMD or PowerShell. py -m pip install pyautogui is often reliable. Run as Administrator for global installs if needed (prefer venvs/--user).
macOS / Linux: Use the Terminal. Use pip3 or python3 -m pip. Use sudo cautiously for global installs. You might also need to install prerequisite system libraries depending on your distribution (e.g., sudo apt-get install python3-tk python3-dev on Debian/Ubuntu, or similar commands for X11 libraries). Check the PyAutoGUI documentation for platform-specific dependencies.
VS Code: Use the integrated terminal (Ctrl + `` ). Ensure the correct Python interpreter (often venv) is selected.
PyCharm: Use the Terminal (Alt+F12) or the Python Packages tool. Verify the correct project interpreter is set.
Anaconda: Use the Anaconda Prompt/Navigator or terminal in an active conda environment.
```
conda install -c conda-forge pyautogui # Preferred in Conda
```
Jupyter Notebook: Install from a notebook cell:
```
!pip install pyautogui
```
Restart the kernel after installation.

Using `pyautogui` After Installation

Once installed, you can import and use the library:

import pyautogui
import time

try:
    print("Getting screen size...")
    screenWidth, screenHeight = pyautogui.size()
    print(f"Screen width: {screenWidth}, Screen height: {screenHeight}")

    print("Moving mouse to center...")
    pyautogui.moveTo(screenWidth / 2, screenHeight / 2, duration=1)
    print("Done.")

except ImportError:
    print("Error: 'pyautogui' module not found.")
    print("Please install it using: pip install pyautogui")
except Exception as e:
    print(f"An error occurred with PyAutoGUI: {e}")

Linters like Pylance (in VS Code) might show this warning even if the package is installed. This usually means:

Incorrect Interpreter Selected: The IDE is not looking at the Python environment where pyautogui was installed. Use the "Python: Select Interpreter" command (Ctrl+Shift+P) in VS Code to choose the correct one (especially the one inside your virtual environment).
IDE Needs Restart: Sometimes, simply restarting VS Code or PyCharm resolves the issue after installing a package.
Linter Glitch (Workaround): As a last resort, if you're sure the package is installed correctly and your code runs, you can suppress the Pylance warning for that specific line:
```
import pyautogui  # type: ignore
```

Conclusion

The ModuleNotFoundError: No module named 'pyautogui' error indicates that the pyautogui package is missing from your active Python environment.

The standard solution is installing it via pip install pyautogui.
Pay close attention to using the correct pip command and ensuring you're working within the intended virtual environment.
Verifying your IDE's selected interpreter is also crucial for resolving both the ModuleNotFoundError and related linter warnings.