How to Resolve "ModuleNotFoundError: No module named 'pyautogui'" in Python
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):
# If you primarily use Python 3
pip3 install pyautogui
# If pip/pip3 are not in your system PATH
python -m pip install pyautogui
python3 -m pip install pyautogui
# On Windows, 'py' launcher might be available
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 thepip
linked to the Python interpreter running your script (usuallypip3
orpython3 -m pip
for Python 3). Check versions:python --version
,pip --version
(orpip3 --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:
# Create (if needed)
python3 -m venv venv
# Activate (adjust for your OS)
source venv/bin/activate # Linux/macOS
.\venv\Scripts\Activate.ps1 # Windows PowerShell
.\venv\Scripts\activate.bat # Windows CMD
# Install INSIDE the active environment
pip install pyautogui - Confirm your IDE (VS Code, PyCharm) is using the Python interpreter from your activated virtual environment.
- Activate your virtual environment before installing:
- Permissions Issues (
--user
orsudo
): 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.
- Recommended: Install for the current user:
- 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 namedpyautogui.py
. This "shadows" the installed package. Rename your file if necessary. Avoid usingpyautogui
as a variable name before the import.
Verifying Installation (pip show
)
Confirm the package is installed in the active environment:
pip show pyautogui
# Or variants like: pip3 show pyautogui / python3 -m 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
orpython3 -m pip
. Usesudo
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
# Or use pip within conda:
# pip install pyautogui - Jupyter Notebook: Install from a notebook cell:
Restart the kernel after installation.
!pip install pyautogui
# Or: !pip install pyautogui --user
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:
# PyAutoGUI can raise various exceptions depending on the OS and setup
print(f"An error occurred with PyAutoGUI: {e}")
Related IDE Error: "Import "pyautogui" could not be resolved..."
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
warningOnly use
# type: ignore
if you are certain the installation is correct and the problem lies with the linter. It hides potential real import errors.
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.