Embedded Files
Compiled by Dr. Sue Lynn Mah’s Lab — November 2025
A guide for new users learning PsychoPy.
Includes setup advice, troubleshooting notes, and insights from the lab's research assistants.
🗂️ Good Practices
✅ Always create and save your PsychoPy experiment in a new folder locally (not OneDrive or Google Drive).
This prevents path errors and keeps your files organized.
✅ Use meaningful and unique names for everything:
Routines: trial, practice_trials, instructions (instead of trial_2, trial_3)
Loops: trials_loop, practice_loop (instead of loop_2, loop_3)
Components: word_stim, instruction_text, practice_image (instead of the default text, text_2)
✅ To copy a Routine:
Go to Experiment → Copy Routine, then Experiment → Paste Routine.
Give it a new name when prompted. PsychoPy will add “_2” to the copied components — rename these to meaningful ones right away.
👉 Protip: Press Ctrl + F to search for a component quickly.
📏 Use “Height” Units
PsychoPy uses height units by default, which scale across different screens:
1.0 = full screen height
0.5 = half screen height
This makes your task display properly across monitors, laptops, and tablets.
🗨️ PsychoPy-isms
PsychoPy uses letterHeight and foregroundColor for text display settings.
letterHeight = font size
foregroundColor = font colour
But why?
letterHeight specifies the physical height of letters, allowing precise control over their size on the screen, which is important for visual experiments.
foregroundColor refers to the color of the letters themselves (the “foreground”), distinguishing it from the background and keeping terminology consistent across different types of stimuli.
This ensures text appears accurately and consistently, regardless of screen size or device.
Examples:
textStim = visual.TextStim(win, text='Hello', letterHeight=0.05)
textStim = visual.TextStim(win, text='Hello', foregroundColor='red')
🧩 Error Messages Are Your Besties 🤗
PsychoPy has three main windows:
Builder: where you’ll spend most of your time
Coder: for custom Python code
Runner: where you’ll see the error messages
If your experiment runs smoothly → ✅ Experiment completed
If it crashes → ❌ Exit Code [1]
🛠️ Common Errors & Fixes
NameError: name 'variable' is not defined
Check that Set every repeat is selected
Make sure $ is used where needed
Ensure your variable name matches the Excel header exactly (case-sensitive!)
Verify the Excel file is attached to your loop and located in the same folder
Syntax Errors (commas, brackets, or quotation marks missing):
Read the error message carefully — it usually tells you the exact line and type of issue.
🧠 No Need to Reinvent the Wheel!
PsychoPy comes with built-in demos of common cognitive tasks.
Go to Demos → Unpack Demos and save them in a folder (e.g., “My Documents”).
Then go to Demos again — you’ll now see a list of ready-to-use examples.
You can also find and adapt tasks from online repositories.
Click on the buttons to learn more!
👻 PsychoPy Isn’t Scary (Promise!)
If PsychoPy ever feels intimidating, remember — everyone starts off feeling the same way!
Even experienced users (and my own research assistants!) once faced that first round of red error messages.
Now, both my RAs are running full PsychoPy projects in my lab. Here’s what they shared about their experience:
1. How did you feel when you first used PsychoPy?
Nathelie Tey: I felt excited at first, but I started struggling when my experiment couldn’t run and kept showing errors, even though I followed every step with my tutor. I didn’t realize that I was overlooking small details, which often caused the errors and made the process quite frustrating.
Kyle Lee: I was fascinated by it at first, but started getting increasingly frustrated when error codes and program crashes became increasingly common.
2. If you were struggling, how did you overcome these?
Nathelie Tey: When I struggled, I reminded myself not to panic or feel anxious. Instead, I asked my friends and tutor during tutorial sessions or made appointments for consultations to clarify my doubts. This approach helped me stay calm and understand the logic behind each component better.
Kyle Lee: Read the official documentation provided by the developers. If that still doesn't work, you can check out the Official Forum and post a question there.
3. What’s the one thing you wish you knew back then so that you can have a “smoother journey”?
Nathelie Tey: I wish I had paid more attention to the “slides” during lectures, so I could better understand the key meanings and functions behind each component and tried exploring everything in PsychoPy to understand how each part works in practice.
Kyle Lee: I should've read the documentation (manuals for specific components in PsychoPy - image component, textbox component) more thoroughly when encountering problems, as most of my issues stem from small beginner errors.
4. What’s one tip you would like to give for first-time users?
Nathelie Tey: Be detailed. Even small things like lowercase and uppercase letters can cause errors. Always ask questions whenever something is unclear instead of waiting until the last minute. Lastly, be brave to try things out, don’t be scared or worried about making mistakes!
Kyle Lee: Save often and keep backups of your work.
🪄 Takeaway
Everyone struggles at the start — even those now building full projects! The trick is to stay calm, ask for help, read the documentation, and save often. Every mistake just means you’re learning how to think like an experiment programmer.
You’ve got this 💪
Page updated
Google Sites
Report abuse