How to Resolve "ModuleNotFoundError: No module named pygame" in Python

The error ModuleNotFoundError: No module named 'pygame' means Python can't find the pygame library, which is used for game development. This usually happens because pygame isn't installed, is installed in the wrong environment, or your IDE/Jupyter isn't set up right.

This guide provides a complete walkthrough for installing pygame and fixing common problems.

Installing pygame (The Basic Solution)

The standard way to install pygame is using pip:

pip install pygame

• Multiple Python Versions: If you have multiple Python versions, use pip3 (or pip3.9, etc.):

  pip3 install pygame

• Permissions Errors: If you get a permissions error:

  sudo pip3 install pygame  # Linux/macOS (use with CAUTION!)
  pip install pygame --user # Install for the current user only

  Using virtual environments (explained below) is the best way to avoid permissions issues.

• python -m pip: If pip isn't in your PATH:

  python -m pip install pygame  # Or python3 -m pip, py -m pip

• Anaconda: if you are using Anaconda, install pygame using:

  conda install -c anaconda pygame

Verifying the Installation

After installing, verify that pygame is accessible with a simple script:

import pygame

print(pygame.__version__)  # Print the pygame version

pygame.examples.aliens.main()

• If this code runs without errors and opens the example, then the installation was successful.

If you get a ModuleNotFoundError, proceed to troubleshooting.

Troubleshooting ModuleNotFoundError

Virtual Environments (Essential)

Always use virtual environments:

1. Create: python3 -m venv venv (or python -m venv venv, or py -m venv venv)

2. Activate:

   • Linux/macOS: source venv/bin/activate
   • Windows (cmd): venv\Scripts\activate.bat
   • Windows (PowerShell): venv\Scripts\Activate.ps1
     • If you get PowerShell errors, use this to enable script execution:

       Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

3. Install: pip install pygame (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, python -m pip) that corresponds to your intended Python version.

IDE Configuration (VS Code, PyCharm)

Configure your IDE to use the correct interpreter/environment.

Jupyter Notebook

Install within a notebook cell:

!pip install pygame

Naming Conflicts

Never name your files pygame.py.

Reinstalling pygame

pip uninstall pygame
pip install pygame

Installation Instructions for Specific Environments

Windows

• CMD or Powershell
• Use pip install pygame, or py -m pip install pygame

macOS / Linux

• Open terminal.
• pip3 install pygame

Ubuntu/Debian/Mint

You might also install pygame using apt:

sudo apt-get install python3-pygame

CentOS/Fedora/Red Hat

sudo yum install python3-pygame

OpenSUSE:

sudo zypper install python3-pygame

Arch/Manjaro

sudo pamac install python-pygame

Anaconda

conda install -c anaconda pygame

Jupyter Notebook (within a cell):

!pip install pygame

Handling "Import 'pygame' could not be resolved" (Pylance - VS Code)

• Select the correct Python interpreter, or restart VS Code.
• Add the comment # type: ignore to the import statement to disable the warning.

import pygame # type: ignore

Conclusion

The ModuleNotFoundError: No module named 'pygame' error almost always indicates an installation or environment issue.

• Always use virtual environments.
• Install with the correct pip command.
• Ensure your IDE/Jupyter setup is correct.

This guide provides comprehensive steps for installation, verification, and troubleshooting, enabling you to start creating games with Pygame.