How to Fix the Python Error: modulenotfounderror: no module named 'pygame'

Python is well known for its impressive ability to meld easy-to-understand syntax with a wealth of additional programming libraries. These libraries can even leverage Python’s ability to “wrap” code created in different programming languages. PyGame is one of the most famous examples of this process. It brings SDL (Simple DirectMedia Layer) functionality to Python. And PyGame also provides a number of game development functions on top of that already powerful base. However, the fact that it’s not a fully native library can make it slightly more difficult to use than Python’s standard modules. And many people interested in trying PyGame have instead found themselves confronted with a “modulenotfounderror: no module named ‘pygame'” error. But this error is relatively easy to both understand and fix.

Basic Analysis of the Module Not Found Error

In the simplest terms the “modulenotfounderror: no module named ‘pygame'” simply notifies us that Python’s interpreter couldn’t find the library files associated with PyGame. Libraries in Python are used with an include statement at the beginning of our code. And if the include statement fails Python will issue a module not found error. The failure to find PyGame is the crux of the problem. But we’ll need to delve a little deeper to determine the potential root causes.

A More In-Depth Look Into the Error and PyGame

The most common cause of a module not found error is that the module simply hasn’t been installed. Very few operating systems or distributions ship with PyGame installed by default. There are exceptions, Raspbian is one notable Linux distribution that ships with PyGame preinstalled. But if you want to use PyGame you’ll typically need to install it yourself. And this can lead to situations where PyGame is improperly installed. The end result is an incomplete or missing installation that Python’s interpreter won’t be able to make proper use of.

Another common issue comes down to the way many operating systems and development environments handle Python’s versioning. Various Python versions tend to come with some level of incompatibility with each other. And this is especially true of the 2.x and 3.x branches. As such, it’s quite common for both Python’s 2.x and 3.x versions to ship on the same system. This can cause some conflicts when working with third-party libraries.

On top of this, many IDEs manage installations separately from the operating system as a whole. You might even have multiple tools on your computer that try to automate Python’s installation process. For example, Ubuntu can install Python’s libraries through apt, pip2 and pip3. The end result is that it’s not always obvious where Python’s libraries are being installed. Likewise, it’s possible for an installation to work with a different version than you’d intended. You might install PyGame successfully. But you’ll still receive the Python error if PyGame was installed for 2.x and you’re using 3.x. Likewise, if you’re using 2.x and installed PyGame for 3.x.

How To Fix the Module Not Found Error

Fixing this Python error is usually easy. But it’ll take a few more steps to troubleshoot the issue before implementing a proper solution. We’ll need to begin by double-checking how you’re actually running Python.

If you run Python’s interpreter with an explicit declaration of the version then you’ll already know which release you’re using. For example, if you type python3 to run the interpreter then you’re running Python’s 3.x branch. If you type Python2 then you’re running the 2.x branch. But if you simply type Python’s name without a version number then you’ll need to type the following on your command line.

python –version

This will return the version number you’re using. You’ll now want to double-check that you’re using a compatible version of the pip installer program. Type the following on the command line.

pip –version

Pip should return some versioning information. But the most relevant part comes at the very end. You’ll see which of Python’s versions pip is working with. You’ll need both Python’s interpreter and pip to be on the same version. If they’re not then you’ll need to manually call the correct version of pip.

Different systems will install pip in different locations. But Unix-based systems usually install pip in /usr/bin. While Windows-based systems typically install pip in Python’s scripts directory. If you’re not seeing the correct versioning then you’ll need to make sure you manually call the proper pip version. For example, on Windows, instead of typing pip you’d type C:\Python27\scripts\pip.exe. Though this will of course differ depending on Python’s installation path and version on your system.

The rest of the fix is fairly simple. You’ll just need to type the following command. With the pip command changed, if necessary, to match your system’s status. For example, you might need to type pip3 if pip is installed under that name in your development environment.

pip install pygame

This will tell the pip installer to download and install PyGame and any associated binaries for you. The big benefit of using pip comes from the fact that it gets around any of the uncertainty that comes with distribution packages or executable-based installers. Pip is part of Python’s environment and will configure everything on its own. Or, at least, as long as you’re using the correct version of pip that’s compatible with Python’s installation. Which at this point you can be sure of. Now run the following Python code.

import pygame
print (pygame.ver)

The code should run smoothly and without the previous error message. Instead, it should import PyGame successfully and then print some basic information about its state to the screen.

How to Fix the Python Error: modulenotfounderror: no module named 'pygame'
Scroll to top