If you searched for Flappy Bird Python code on GitHub, you want a working Pygame clone you can download, run immediately, and then poke around in. The best starting points are sourabhv/FlapPyBird and mehmetemineker/flappy-bird, both actively maintained Pygame projects with clear READMEs, asset folders, and single-file entry points. Clone either one, install Pygame, run the entry point from the repo root, and you have a playable game in under five minutes. Everything below walks you through picking the right repo, setting up your environment, understanding how the code actually works, and customizing it to make it your own.
Flappy Bird Python Code on GitHub: Run and Modify
Maya Hennessy
4 Jun 2026
Clarifying what you're looking for: Flappy Bird in Python on GitHub
Flappy Bird is a 2013 mobile game, not a real bird species, though its unforgiving precision and constant failure points do feel oddly appropriate for a site that studies how fragile survival can be. Galápagos has a real bird that cannot fly, the perfect example of how nature can be different from a “bird” in pop culture Galápagos bird that can't fly. On GitHub, 'flappy bird python' overwhelmingly refers to Pygame clones: fan-made recreations of the tap-to-fly mechanic using Python's most popular game library. Some repos add an AI agent (usually NEAT or Q-learning) that learns to play the game automatically. If you just want to play and read the code, stick to the manual-play repos. If you want to watch a neural network master it, look for repos with 'AI' in the title, like Yuanpeng-Li/Flappy-Bird-AI, which also includes a human play mode.
How to find a good GitHub repo for this project
There are dozens of Flappy Bird Python repos on GitHub and most of them are fine for learning. The trick is filtering for ones that are actually complete and runnable. Here is what to check before you clone anything.
- README mentions Pygame or pygame-ce by name and gives explicit run instructions (a line like 'python3 main.py' or 'make run').
- There is a single obvious entry point: main.py, flappybird.py, or humanflappy_bird.py referenced directly in the README.
- An assets or imgs folder exists in the file tree and contains sprite files named things like bird1.png, bird2.png, pipe.png, and base.png.
- A requirements.txt or pyproject.toml is present so you know exactly what to install.
- The README has a Setup or How to Play section, not just a one-line description.
Using those signals, three repos stand out. sourabhv/FlapPyBird has a src/ folder, an assets/ folder, a main.py entry point, and a pyproject.toml. mehmetemineker/flappy-bird uses Pygame explicitly and tells you to run 'python3 main.py' and restart with ESC after a collision. Yuanpeng-Li/Flappy-Bird-AI goes further by pinning Python 3.9.18 in its conda setup and providing a requirements.txt, which is especially useful if you have had version mismatch headaches before.
Setting up and running the code locally
These steps work for the majority of repos. Swap out the repo URL and entry point filename to match whichever one you picked.
- Make sure Python 3.9 or higher is installed. Python 3.9.18 is the safest choice if you are using Yuanpeng-Li/Flappy-Bird-AI; for the others, Python 3.10 or 3.11 works fine.
- Clone the repository: git clone https://github.com/sourabhv/FlapPyBird.git (or whichever repo you chose), then cd into the project folder.
- Create and activate a virtual environment: python3 -m venv venv, then source venv/bin/activate on Mac/Linux or venv\Scripts\activate on Windows.
- Install dependencies. If there is a requirements.txt, run pip install -r requirements.txt. For sourabhv/FlapPyBird, run make init (which does the pip install step for you). For Yuanpeng-Li/Flappy-Bird-AI, you can also use conda create -n flappybird python=3.9.18 before the pip install step.
- Run the game from the repo root directory: python3 main.py (mehmetemineker/flappy-bird and sourabhv/FlapPyBird) or python3 main/humanflappybird.py (Yuanpeng-Li/Flappy-Bird-AI). For sourabhv/FlapPyBird you can also just run make.
- Controls: Space or the Up arrow to flap. ESC to quit or restart after a collision, depending on the repo.
The single most important rule is to always run the script from the repo root, not from inside a subdirectory. Almost every repo loads its sprites using relative paths like os. In flappybird.py from RSourceCode/AI-Flappy-Bird, the game loads its sprite images via relative paths like bird*.png, pipe.png, and base.png. path.join('imgs', 'bird1.png'), so if your working directory is wrong, Python cannot find the image files and the game crashes immediately with a FileNotFoundError.
How the code is structured and how the game loop works
Most of these repos follow the same structural pattern: a main script that initializes Pygame, sets up sprite groups, and runs an infinite while loop until the player quits. Inside that loop, the game clock ticks at a fixed FPS (usually 30 to 60), entities are updated, the screen is redrawn, and collision checks are run. Understanding this pattern makes any Flappy Bird repo readable.
| Component | What it does | Typical file/class |
|---|---|---|
| Game loop | Calls clock.tick(FPS), updates sprites, redraws screen each frame | main.py or flappy_bird.py |
| Bird / Player class | Holds position, velocity, and sprite; updates gravity and handles flap input | Bird or Player class |
| Pipe class | Moves pipes left at constant speed; pairs of top/bottom pipes with a gap between them | Pipe or Obstacle class |
| Asset loader | Loads PNG/WAV files from assets/ or imgs/ using relative paths at startup | Top of main file or separate utils module |
| Score tracker | Increments when the bird clears a pipe; often a simple integer drawn to screen each frame | Inside the main loop |
Pipe spawning uses a time-based schedule rather than a frame counter. A pattern you will see in almost every repo: timeNow = pygame.time.get_ticks(), and then if timeNow - lastPipe > pipeFrequency: a new pipe pair is created and lastPipe is reset. This keeps spawning consistent regardless of frame rate fluctuations.
The key implementation details worth understanding
Physics and controls
Gravity is simulated by adding a small constant to the bird's vertical velocity every frame: self.velocity += 0.5. There is usually a terminal velocity cap to prevent the bird from accelerating forever, commonly around 8.5 pixels per frame. When the player taps Space or the Up arrow, the flap sets the velocity to a negative value (upward in Pygame's coordinate system where y increases downward): self.velocity = -10. That's really all the physics there is. Two tunable numbers define the entire feel of the game.
Collision detection
Collisions are handled with Pygame's built-in rectangle (AABB) system. The bird and all pipes are sprites with a rect attribute. The main loop checks pygame.sprite.groupcollide(birdGroup, pipeGroup, False, False) to catch bird-pipe hits, and separately checks bird.rect.top < 0 or bird.rect.bottom >= screen_height for ceiling and ground collisions. If any of those conditions are true, the game transitions to a game-over state.
Scoring and restart
Scoring uses a simple flag called passPipe (or equivalent). Each frame, if the bird's left edge has just passed the right edge of the nearest pipe, passPipe becomes true and playerScore increments by 1. The flag is reset so it only counts once per pipe pair. On game over, most repos display the score and wait for input: mehmetemineker/flappy-bird uses ESC to restart, while sourabhv/FlapPyBird accepts Space to replay.
Common issues and how to fix them
| Problem | Cause | Fix |
|---|---|---|
| FileNotFoundError on bird1.png or pipe.png | Script run from wrong directory | cd to the repo root before running python3 main.py |
| ModuleNotFoundError: No module named 'pygame' | Pygame not installed in the active environment | Run pip install pygame (or pip install -r requirements.txt) |
| pygame.error: No video mode has been set | Display not initialized before loading images | Make sure pygame.init() and pygame.display.set_mode() come before any image.load() calls |
| Slow or choppy performance | FPS not capped or running in a heavy virtual environment | Check that clock.tick() is being called; lower FPS value slightly if needed |
| Wrong Python version errors (f-strings, walrus operator) | Repo uses Python 3.8+ syntax but you have Python 2 or older 3.x | Install Python 3.9+ and point your virtual environment to it |
| Game window opens then immediately closes | Runtime error silently crashing before the loop starts | Wrap main() in a try/except and print the traceback to see the real error |
The asset path issue is by far the most common one beginners hit. Because images are loaded with relative paths, the game assumes it is being run from the folder that contains imgs/ or assets/. Running python3 src/main.py from a parent directory will break things even if the file path looks right. Always navigate into the repo folder first.
Ways to customize and improve the project
Once you have the game running, the code is remarkably easy to modify because all the key values are just constants at the top of the file. Here are the most satisfying things to change.
Difficulty tuning
Two constants control almost everything about difficulty: pipeFrequency (the milliseconds between pipe spawns, often defaulting to 1450) and pipeGap (the vertical space between top and bottom pipes, often 150 pixels). Decrease pipeFrequency to spawn pipes faster. Decrease pipeGap to make the opening tighter. You can also increase the pipe scroll speed or reduce the flap impulse (-10) to make the bird feel heavier. Even small changes produce a dramatically different feel, which makes this a great sandbox for experimenting with game balance.
UI and visual improvements
Replace the default sprites with your own PNG files at the same dimensions and the game will use them automatically, since the loader just reads whatever file is at the expected path. You can add a high score display by storing the best score between game-over screens in a simple variable. A parallax scrolling background (two copies of the background image scrolling at different speeds) adds visual depth with very little extra code.
Sounds and feedback
Pygame's mixer module handles audio. Load a flap sound with pygame.mixer.Sound('assets/flap.wav') and call sound.play() inside the flap logic. Add a point sound when the score increments and a collision sound on game over. Most repos already have placeholder WAV files in their assets folder, so it is often just a matter of uncommenting the audio calls or adding two lines.
Where to go next after you have it running
Reading a working Flappy Bird clone is one of the best ways to internalize Pygame patterns: the clock-tick loop, sprite groups, rect-based collisions, and time-based scheduling all appear in almost every 2D Pygame game. Once those feel familiar, the natural next step is building your own repo from scratch instead of cloning. Start with a blank Pygame window, add a falling rectangle as your bird, add gravity and a flap impulse, then add pipes. Building it piece by piece makes every line of code mean something. If you are wondering about whether Big Bird actually went to jail, that is more about celebrity trivia than game-code practice did big bird go to jail.
For structured learning, the GeeksforGeeks Pygame Flappy Bird tutorial walks through creating each entity and adding the main loop with pygame.time.Clock() step by step. The official Pygame documentation at pygame.org is worth bookmarking for sprite, rect, and mixer reference. If you want to go further and add an AI agent, Yuanpeng-Li/Flappy-Bird-AI is a clean starting point since it separates the human play mode from the AI mode, making it easy to study both.
When you are ready to publish your own version, create a new GitHub repo, add a clear README with setup instructions and a screenshot, include a requirements.txt with your pinned Pygame version, and make sure your assets folder is committed alongside the code. A repo that someone else can clone and run in five minutes is infinitely more useful than one that works only on your machine. That same principle applies whether you are archiving game code or documenting a vanishing bird species: the record is only valuable if others can actually access it. For background on the viv bird plane crash in Greenland, see the related incident coverage and timeline.
FAQ
Why does my Flappy Bird clone work on one machine but crashes with missing images on another? (FileNotFoundError)
Yes, but only if you keep your game’s assets paths working. The simplest approach is to run the entry point exactly the way the repo README suggests (from the repo root), because most clones reference files like imgs/... or assets/... with relative paths. If you want to run it from elsewhere, change the loader to build absolute paths from the script location (for example, using the file’s directory via __file__).
My pipes spawn too quickly or unevenly. How can I tell if the repo is using time-based spawning correctly?
If your pipes feel inconsistent, it is usually because your spawn logic is tied to frames instead of time. Look for a condition that uses pygame.time.get_ticks() and a pipeFrequency style threshold, then compares timeNow - lastPipe. If a repo uses a frame counter, try converting it to time-based scheduling so gameplay stays stable when FPS fluctuates.
What are the best constants to tweak if the bird feels floaty or too heavy?
In most clones, you do not need to overhaul physics. Start by adjusting the two constants that control the feel: the flap impulse (the negative velocity set on input) and gravity (the per-frame velocity increment). If the bird is moving too slow overall, increase gravity slightly, and if jumps do not reach the pipe openings, make the flap impulse more negative.
Should I worry about Python or Pygame version mismatches when running flappy-bird python code github projects?
Many repos assume a specific Python version, and differences can show up especially with dependency resolution. If the repo includes a conda setup or pins Python (like a requirements.txt plus a recommended Python 3.x), follow that. If you run a different Python version and see Pygame install or runtime issues, create a fresh virtual environment and reinstall from the repo’s requirements or pyproject.toml.
Why does pressing Space or Up sometimes not flap reliably?
Yes, the common cause is input handling in the main event loop. Ensure the code listens for KEYDOWN (not just key state polling) and that flap triggers only when the event occurs. Also check if the repo binds to Space and Up arrow separately, and confirm there is not a cooldown or state flag preventing repeated flaps within the same frame.
My score increments multiple times per pipe or never increments at all. What should I check?
Score bugs often come from the “passPipe” style flag not being reset, or from using the wrong edge comparison. Verify the logic increments only when the bird’s x position passes the nearest pipe’s x boundary, and that the flag resets for each new pipe pair. Also confirm the nearest pipe selection (or list ordering) matches how pipes are stored.
The game shows game-over, but the bird keeps moving or the screen keeps updating. How do I fix it?
Try adjusting how the game-over state is triggered and when the loop stops updating. If game-over transitions but sprites keep moving, the code likely continues the update loop or does not gate updates behind a 'running' or 'gameOver' flag. Look for a boolean that breaks the while loop, or route updates only when not in the game-over state.
Audio does not play, but the game runs. What are the most likely causes in these GitHub Flappy Bird clones?
Audio issues are usually about initialization or file paths. Pygame mixer often requires pygame.mixer.init() (some repos call it already), and the sound loader paths must match the repo’s working directory and assets folder naming. If you get silent audio, print or log whether the Sound('assets/flap.wav') call succeeds, then confirm the WAV files exist at that relative path.
How do I modify an AI Flappy Bird repo (with NEAT or Q-learning) to test changes without keyboard interference?
For AI repos, be careful about mixing human and AI controls. Many implementations keep a human play mode and an AI play mode, but the update loop might still read keyboard events even when the AI is active. Ensure the AI mode bypasses input handling and instead sets the flap action based on the agent’s decisions each step.
What should I include in my GitHub repo so others can run my Flappy Bird Python code immediately?
When you publish your own clone, commit both code and assets, and add a requirements.txt or pin Pygame in a consistent way. Also include a screenshot and the exact run command from the repo root. This prevents the two biggest friction points: relative asset paths and users installing a different Pygame version than the one your code expects.