Current Instructions

These should work on both x86_64 and arm64 macs, running MacOS 10 and above

With dependencies installed with homebrew

1. Install Homebrew -- instructions found on link.
Install the SDL dependencies:

brew install sdl2 sdl2_image sdl2_mixer sdl2_ttf pkg-config

2. Install XQuartz [Seems to be optional]

brew install Caskroom/cask/xquartz

3. Install portmidi
This step is definitely optional, and may fail on your system (it fails on mine). If you don't run this, or it fails, pygame.midi won't work, which is fine for most people. (step 5, testing, will tell you if this worked or not).

brew install portmidi

4. Install latest Pygame from source

python3 -m pip install git+

5. verify all Pygame Tests

python3 -m pygame.tests

Legacy Instructions

2017 instructions

Python3 and Pygame on macs can have a special setup. Try and follow the instructions on here, if you have the newest macOS. Make sure to follow the instructions designated for Python3. If those instructions don't work, click the source link on that answer, which goes to an article made for older macs.

Installing from source with homebrew

Homebrew is a package manager that's very popular on Mac. We use that to get the dependencies for pygame.

brew upgrade sdl sdl_image sdl_mixer sdl_ttf portmidi
python3.6 -m venv anenv
. ./anenv/bin/activate
pip install

If you want to install the last release, change the pip install part to:

pip install

Other instructions

The following page details how to install PyGame 1.9.1 on a Mac OS X 10.6 (Snow Leopard) running the most recent 2.x version of Python (2.7.1).

Here are some alternative methods for installing PyGame on osx:

Mountain Lion install instructions

1. Installed python but using visual python version. This is based on python 2.7.x
In my system this installs files under Applications and /Library/Frameworks/Python.framework
From this site:

First, download and install the pure 32-bit Python, Python-2.7.3
(VPython does not work with Mac 64-bit/32-bit Python, but this 32-bit version of Python works fine on 64-bit Macs)

Second, download and install VPython-Mac-Py2.7-5.74

This includes version 1.5.1 of numpy.

The download of Python-2.7.3 is from the vpython site and designed to work with vpython.
You can use the python installer from However, you will have to install numpy.
You can get numpy from

2. Installed the SDL libraries from dmg

SDL  1.2.15
SDL_mixer 1.2.12
SDL_ttf  2.0.11
SDL_image 1.2.12

3. Installed the libjpeg and libpng libraries from dmg

libpng v1.5.4
libjpeg 8c

4. Installed Xcode 4.4 from Apple apps. Need to add command line tools.
To do this start Xcode and go to Preferences under Xcode menu. Choose the Download tab and select Components.
Then install the Command Line Tools.

5. Installed XQuartz. Mountain Lion OS X no longer includes the X11 window system library.
This is different from Lion OS X.


6. Downloaded pygame tar file from


Decompressed and extracted to create directory pygame1.9.1release

6. Before compilation of pygame:

  a. SDL_x header files refer to SDL as &ltSDL/SDL_yy.h> However, a SDL directory is not under
the include directory of SDL (SDL/Headers). To fix this in a simple way:

    i. Went to directory
     then made a link as follows:
          ln -s SDL ./

7. Changed to the pygame directory (normally pygame1.9.1release). Then switched to the super user.
However, you can use the sudo command instead.

I set the following compilation flags

export CC='/usr/bin/gcc'
export CFLAGS='-isysroot /Applications/ -I/opt/X11/include -arch i386'
export LDFLAGS='-arch i386'
export ARCHFLAGS='-arch i386'

You must specify using the original location of X11. The mac does not have a
and apparently the links generated by XQuartz in /usr do not work correctly.

8. Now execute:
This should find the SDL, jpeg, png, and numpy libraries

   python build
This will build in the directory before installing. It should complete with no errors.
   python install

9. Confirmed that it worked:

   Out of super user mode and in a terminal shell

   and within python
   import pygame

   this gave no error and a simple pygame program ran fine.

GAMercier 2012-08-05

Snow leopard install instructions.

Set these environment flags before building...

export CC='/usr/bin/gcc-4.0' CFLAGS='-isysroot /Developer/SDKs/MacOSX10.5.sdk -arch i386'
export LDFLAGS='-arch i386'
export ARCHFLAGS='-arch i386'

If you get this error:

/Developer/SDKs/MacOSX10.4u.sdk/usr/include/stdarg.h:4:25: error: stdarg.h: No such file or directory

This link has a solution:


first, get the following packages:

SDL frameworks

Tested with the latest python 2.7.x (2.7.1) framework:

Build and install

Install the SDL Frameworks

Open the DMG files and read the included Readme files to determine what needs to be moved where. The normal process is to go to each opened volume (/Volumes/SDL_something) directory, and run the appropriate following command:

sudo cp -R SDL.framework /Library/Frameworks/SDL.framework sudo cp -R SDL_image.framework /Library/Frameworks/SDL_image.framework sudo cp -R SDL_ttf.framework /Library/Frameworks/SDL_ttf.framework sudo cp -R SDL_mixer.framework /Library/Frameworks/SDL_mixer.framework

Install pyobjc (non-Leopard only)

Unpack the tgz tar xvzf pyobjc-1.4.tar.gz cd pyobjc-1.4 Build and install python bdist_mpkg --open

Install Numeric

Unpack the tgz tar xvzf Numeric-24.2.tar.gz cd Numeric-24.2 In OSX Leopard, you will need to comment out three lines (152-154) in /Packages/RNG/Src/ranf.c //#if !defined(__sgi) // int gettimeofday(struct timeval *, struct timezone *); //#endif Build and install sudo python install

Install Universal build libjpeg & libpng

pygame needs universal binaries to build right, but libpng and libjpeg sources don't build as universal binaries automatically... so you probably want to download the pre-built universal binaries for libpng & jpeg from However you probably don't want to build against the dylib's for libpng and libjpeg if you are making an installer or will be using py2app, because then your distribution's will not work without your clients also installing the libjpeg and libpng pacakges.
Since the package above installs both dylib and .a versions to /usr/local/lib and the build process will use the dylib versions by default, this means you probably want to delete/rename the dylib versions

Install the package

sudo rm /usr/local/lib/libpng.dylib sudo rm /usr/local/lib/libjpeg.dylib

Install libjpeg (from source)

Skip this step if you downloaded the pre-built universal binaries for libpng & jpeg

Unpack the tgz tar xvzf jpegsrc.v6b.tar.gz cd jpeg-6b Build and install ./configure make sudo make install-lib

Install libpng (from source)

Skip this step if you downloaded the pre-built universal binaries for libpng & jpeg

Unpack the tbz

tar xvjf libpng-1.2.16.tar.bz2 cd libpng-1.2.16

Build and install

./configure make sudo make install

Install pygame

Unpack the tgz

tar xvzf pygame-1.8.0rc3.tar.gz cd pygame-1.8.0rc3

Configure python The output should be:

Using Darwin configuration... Hunting dependencies... Framework SDL found Framework SDL_ttf found Framework SDL_image found Framework SDL_mixer found Framework smpeg not found NUMERIC : found 24.2 PNG : found JPEG : found

Edit Setup and put a '#' at the start of the line: #scrap src/scrap.c $(SDL) $(X11) Build pygame python build Install pygame sudo python install

pygame with sdl2

Experimental sdl2 support can be compiled in like so: brew install sdl2 sdl2_gfx sdl2_image sdl2_mixer sdl2_net sdl2_ttf git clone cd pygame python -config -auto -sdl2 python install