I have compiled a replicable, dependable, almost understandable set of steps to install Pygame for Python 3 that has worked across four generations of Mac OS X. Pieces of these steps appear in two or three other how-to’s on the web, but this full process has been carefully tested across Mac OS X 10.6-10.9, and I’m posting the steps here to solicit feedback from Pygame-curious Mac users out there.
I had run into a tough situation – I wrote a book this past year using Python as the language, and in the last three chapters, I showed readers how to build playable, interactive games using Pygame. The problem is that Pygame is challenging to get working on Python 3 on a Mac – and a lot of my readers are Mac users.
Mac users have essentially the following three options if they want to use Pygame:
- You can install an older version of Python, like Python 2.7, along with Pygame 1.9.2 for Mac OS X in a new location on your Mac for Pygame programming.
- If you have access to a Windows PC, you may find it easier to install the Windows version of Python and Pygame…
- Or, you can follow the steps listed below to install Pygame for Python 3.4 on your Mac – if you’re doing this at school or at work, you will probably need IT support.
How to install Pygame for Python 3 on Mac OS X successfully, every time:
- Install Xcode: In Finder, open Applications, App Store. Search for Xcode and click Get to install the Xcode developer tools. You’ll need these developer tools to run some of the command-line instructions in a Terminal window below.
- Install XQuartz: Go to https://xquartz.macosforge.org and download the current version of XQuartz (2.7.7 as of this writing). Open your Downloads folder, double-click on the XQuartz-2.7.7.dmg file, then double-click on the XQuartz.pkg package file and follow the instructions to complete the installation.
- Open a Terminal (command-line) window: Go to Applications, Utilities, and double-click Terminal. Your command-line Terminal window will open. All the following commands must be typed exactly as they appear in the Terminal window, one line at a time.
- Install Homebrew: At the Terminal command line prompt, type the following as a single full line (you may want to expand your Terminal window wider to allow it to fit, but it’s okay if it wraps around):
ruby -e “$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)”
then, hit return. Homebrew is a free program that helps you install Python, Pygame, and other programs on a Mac. - Prepare Homebrew for use: At the Terminal prompt, type each of the following three commands exactly as shown – the second two may take a few moments to run and will show several screens of information, but keep following the steps one line at a time.
echo export PATH=’/usr/local/bin:$PATH’ >> ~/.bash_profile
brew update
brew doctor - Install Python 3 for Pygame: At the Terminal prompt, type:
brew install python3
This will install a separate Python 3 specifically for Pygame use – this is required for all the following steps to work. - Install Mercurial: Still at the Terminal prompt, type:
brew install mercurial
Mercurial is a free source control management system that this installation of Pygame requires on a Mac. - Install Pygame dependencies: Pygame requires several other helper programs, called dependencies, so that it can show animations, play sounds, and create game graphics. Type the following three lines at the Terminal command prompt, hitting return after each line
brew install sdl sdl_image sdl_mixer sdl_ttf portmidi
brew tap homebrew/headonly
brew install smpeg
(NOTE 18JUL2015: Updated to reflect changes to the smpeg library; if you have any trouble here, try brew install –HEAD smpeg instead, with two dashes/hyphens before the HEAD option).
Each command will take a few moments to run and display screens full of information; keep going, you’re almost done… - Install Pygame: Type the following line at the Terminal prompt and hit return:
sudo pip3 install hg+https://bitbucket.org/pygame/pygame
You may have to enter an administrator password (your password, or ask an IT administrator for help at school, work, or the library), and the installation may take a few minutes.
As mentioned in step 6 above, this process creates a second full Python environment (under /usr/local/Cellar) on your Mac. You’ll want easy access to your Pygame-enabled Python…
Create a desktop shortcut to your new Pygame IDLE editor:
The new Pygame and Python 3 that you just installed creates a separate IDLE editor app that you’ll use especially for Pygame-enabled apps. (Note: You can use this new IDLE for all your Python development, if you wish.)
- Go to Finder > Go > Go to Folder…
- In the Go to the folder: window prompt, type /usr/local/Cellar/python3 and click Go.
- Double-click to open the folder inside – it will be named with a version number (3.4.2_1 as of this writing), but the version is unimportant, just open the folder.
- Inside this folder, you will find the IDLE 3 app. Hold down the control key and click on the IDLE 3 icon. Pressing control+clicking on the icon will open a popup menu; select the Make Alias option from that menu.
- A new alias, or shortcut icon, will appear, with a name like IDLE 3 alias. Click on the file name to edit it, and rename the alias pygame IDLE or something similar, to help you remember that this IDLE has Pygame installed.
- Drag the pygame IDLE icon to your Desktop. This will allow you to access the correct IDLE for Pygame programming right from your Desktop.
- Double-click the pygame IDLE icon. The Pygame-enabled IDLE editor window will open. Type import pygame and hit return. IDLE should respond with a >>> prompt and no errors.
You’re ready to program Pygame apps on your Mac!
If you’re tough enough to make it through all these steps, and you’re enjoying Pygame on your Mac, please leave a comment and let me know (also leave any corrections/issues) – I hope these instructions will help others have as much Pygame fun as my sons and I have enjoyed these past few years. Cheers!
March 21, 2015 at 11:46 am
Just fyi,
– at the step ‘brew install –HEAD smpeg’, this failed with errors like ‘no available formula for –head’, but after running ‘brew install smpeg’ and being told to run the first command instead, then the first command worked. Most odd.
On OSX 10.9.5
April 3, 2015 at 3:09 pm
D – make sure the previous line (brew tap homebrew/headonly) completed without an error, and double-check that you have double-dashes/hyphens before the uppercase –HEAD.
Let me know if you run into the issue again.
July 18, 2015 at 9:46 am
I had a similar issue to what D reported. Whenever I run ‘brew install –HEAD smpeg’ I get “Error: No head is defined for smpeg”. When I try ‘brew tap homebrew/headonly’ I get “Warning: Already tapped!”. So I just executed ‘brew install smpeg’ without using –HEAD and it seems to have worked. What is the significance of using –HEAD?
July 18, 2015 at 10:39 am
Johnny – thanks for the comment. HEAD installs the latest additions to the master/trunk repo – when I wrote this, the smpeg stable release didn’t have some of the newer components, but it looks like they’ve been committed, so I’ll update above. Thanks for letting me know! – Bryson
November 4, 2015 at 1:19 pm
Hi Bryson! I’m 7 and using your book. I can’t get the YourName.py program to run. I even downloaded the example and it doesn’t run. It’s giving me this error:
Traceback (most recent call last):
File “/Users/CentCom/Downloads/code/ch01/YourName.py”, line 2, in
name = input(“What is your name?\n”)
File “”, line 1, in
NameError: name ‘Ella’ is not defined
I am using Idle 2.7.10 on iOS 10.9.5
Please help me.
Thanks!
January 23, 2016 at 10:52 am
Coding the example programs with Python 2.7
Reader Ella D. (age 7) posted a great question last month, and I replied to her directly, but I wanted to post for everyone – in fact, I’ll make a full new post to help out. Here’s the reply for convenience:
Thank you for the great question! Several readers/students have asked about running the example programs from “Teach Your Kids to Code” in IDLE for Python 2.7 (the common default on Mac or Linux) – the good news is that you have two relatively easy options:
1) Upgrade to Python v3 with sudo apt-get install python3 and sudo apt-get install idle3 (let me know if you’re using a version of Linux that doesn’t work with apt-get, and I’m glad to post a video if it’ll be of help) – all the examples will work as-is for the newer Python/IDLE 3. [See Lecture 9] – OR –
2)Change just the input() and print() statements in any course examples to raw_input(), and print without the parentheses (without the round brackets) for backward compatibility with Python v2.
Example: Here’s what the YourName.py program (from Chapter 1, p. 6 of the book, or Lecture 3 of my Udemy course) would look like for Python 2.7:
# YourName.py - for Python 2.7 from p.6 or Lecture 3 of Teach Your Kids to Codename = raw_input('What is your name?\n')
print 'Hi,', name
The other statements (and almost all turtle examples) should work the same from Python 3 back to Python 2, but the input and print statements changed between versions.
I hope this post this is of help, or message me/reply below if you’d like me to post a video or two – Python 2 is still used widely in the scientific and other communities (and still ships on new Linux/Mac computers). Enjoy either version of Python, and let me know if I can be of help anytime!
Happy coding!
Bryson
February 11, 2016 at 5:45 am
Hi Bryson,
Just wanted to say how helpful I found your description for getting pygame installed for Python 3 on OSX. Worked really smoothly. All I need to do now is figure out how to reduce the number of python installations I have down from four !
Thanks
March 7, 2016 at 2:54 am
Hi, Bryson,
These instructions also worked to install Pygame on my Mac, running OSX 10.11.3. Thanks!
However, there was one unusual issue. The new IDLE 3 app that was installed in /usr/local/Cellar/python3 does NOT run. However, that turns out not to matter, since my old Python 3.4 IDLE app in the Applications folder is now able to run Pygame programs. Perhaps your instructions should be updated to mention that possibility…..
March 7, 2016 at 11:31 am
Steve,
Thanks for your post – that’s great to hear! Glad pygame’s running for you – let me know if I can ever be of help.
Sincerely,
Bryson
August 24, 2016 at 3:34 am
I had the same issue in 10.11.6. It works in my old IDLE too, weird problem that doesn’t seem to matter much 🙂 This tutorial is awesome!
April 28, 2017 at 4:06 am
I also had this issue so just using my old version (in the launchpad). The rest worked a treat! Thank you so much! Was about to give up on pygame entirely!
December 9, 2016 at 2:57 pm
Thank you. This worked for me.
February 19, 2017 at 10:23 pm
Hi, I’m running MAC OS X 10.11.6.
The echo export… command kept corrupting my .bash_profile. Don’t know what was the problem.
I was using Command-C and Command -V to copy the commands to the terminal command line to avoid typos. The quotation marks in the ruby… command line caused me an issue. I deleted those and replaced them with the quotation marks and it worked fine.
Thank you!
March 7, 2017 at 7:13 pm
Hi, just followed the steps above with success. Thank you for doing this
March 13, 2017 at 3:21 pm
So helpful! Thank you!
March 27, 2017 at 12:00 am
Bryson: Thank you very very much! Your instructions saved me many (more) hours of googling. Really appreciate it!
May 5, 2017 at 7:30 am
thank soo much sir..!!!
July 1, 2017 at 9:43 am
Do you think it will be possible for you to program an installer using your skills in code because this would be a great help for future users.
April 1, 2018 at 2:32 pm
/usr/local/Cellar/python3 for me was /usr/local/Cellar/python/3.56
Everything else worked great. Thank you
June 21, 2018 at 1:07 pm
You are a genius my good sir.