Flappy Bird Python Code on GitHub: Run and Modify

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.

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.

1. 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.
2. Clone the repository: git clone https://github.com/sourabhv/FlapPyBird.git (or whichever repo you chose), then cd into the project folder.
3. Create and activate a virtual environment: python3 -m venv venv, then source venv/bin/activate on Mac/Linux or venv\Scripts\activate on Windows.
4. 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.
5. 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.
6. 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.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.

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

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.