Learn GPU Programming in Mojo🔥 Through Interactive Puzzles🧩

Overview • Why Mojo • Getting Started • Development • Community

Overview

"For the things we have to learn before we can do them, we learn by doing them." — Aristotle, (Nicomachean Ethics)

Welcome to Mojo🔥 GPU Puzzles, Edition 1 — an interactive approach to learning GPU programming through hands-on puzzle solving. Instead of traditional textbook learning, you'll immediately dive into writing real GPU code and seeing the results.

Start Learning Now 👉 puzzles.modular.com

📬 Subscribe to updates to get notified when new puzzles are released!

Why Mojo🔥

Mojo represents a revolutionary approach to GPU programming, making massive parallelism accessible while maintaining systems-level performance:

🐍 Python-like Syntax with systems programming capabilities
⚡ Zero-cost Abstractions that compile to efficient machine code
🛡️ Strong Type System catching errors at compile time
📊 Built-in Tensor Support with hardware-aware optimizations
🔧 Direct Hardware Access to CPU and GPU intrinsics
🔄 Cross-Hardware Portability for CPUs and GPUs
🎯 Ergonomic Improvements over traditional C/C++

Getting Started

Prerequisites

You'll need a compatible GPU to run the examples.

Visit puzzles.modular.com
Clone this repository
```
git clone --branch stable https://github.com/modular/mojo-gpu-puzzles
cd mojo-gpu-puzzles
```
The stable branch matches puzzles.modular.com and is pinned to the current MAX release. This repository's default branch, main, tracks nightly builds, so its puzzle code may not compile against the release toolchain. Clone main only if you intend to contribute a change (see Development).
Install a package manager to run the Mojo🔥 programs:

Option 1: pixi (Highly recommended)

pixi is the recommended option for this project because:

Easy access to Modular's MAX/Mojo packages
Handles GPU dependencies
Full conda + PyPI ecosystem support

Note: A few puzzles only work with pixi.

Install:
```
curl -fsSL https://pixi.sh/install.sh | sh
```
Update:
```
pixi self-update
```

Option 2: `uv`

Install:

curl -fsSL https://astral.sh/uv/install.sh | sh

Update:

uv self update

Create a virtual environment:

uv venv && source .venv/bin/activate

Install the puzzles and their dependencies, without which nothing else here runs:

uv pip install -e ".[nvidia]"  # For NVIDIA GPUs
# OR
uv pip install -e ".[amd]"     # For AMD GPUs

Start solving puzzles!

Development

We use pixi for development as it includes uv and also supports conda packages (like mdbook from the conda-forge channel) needed for development workflows.

WSL Users: Before running pixi run book, install the required browser integration package:
sudo apt update && sudo apt install wslu

Older NVIDIA driver workaround: Mojo and MAX require NVIDIA driver ≥ 580 (CUDA ≥ 13.0). Systems still on older drivers (for example, the Jetson Orin shipped with JetPack SDK on driver 540.x / CUDA 12.6) can hit a driver-version error at runtime. Point Mojo at the system ptxas to work around it:
export MODULAR_NVPTX_COMPILER_PATH=/usr/local/cuda/bin/ptxas
The exact path can vary — see the system requirements for the canonical CUDA toolchain locations on each platform. Add the export to your ~/.bashrc (or equivalent shell rc) to make it persistent.

# Build and serve the book
pixi run book
# Test solutions on GPU
pixi run tests
# Or a specific puzzle
pixi run tests pXX
# Or manually
pixi run mojo/python solutions/pXX/pXX.{mojo,py}
# Run GPU sanitizers for debugging on NVIDIA GPUs using `compute-sanitizer`
pixi run memcheck  <optional pXX>    # Detect memory errors
pixi run racecheck <optional pXX>    # Detect race conditions
pixi run synccheck <optional pXX>    # Detect synchronization errors
pixi run initcheck <optional pXX>    # Detect uninitialized memory access
# Or run all sanitizer tools
pixi run sanitizers pXX
# Or manually
# Note: ignore the mojo runtime error collision with the sanitizer. Look for `Error SUMMARY`
pixi run compute-sanitizer --tool {memcheck,racecheck,synccheck,initcheck} mojo solutions/pXX/pXX.mojo
# Format code
pixi run format

Contributing

We welcome contributions! Whether it's:

📝 Improving explanations
🐛 Fixing bugs (report bug)
💡 Suggesting improvements (request feature)

Please feel free to:

Fork the repository
Create your feature branch
Submit a pull request

Keeping problems and solutions in sync

Each problems/pNN/ file is the same as its solutions/pNN/ counterpart except that the student fill-in regions are blanked out with # FILL ME IN hints (and an optional ... placeholder so an empty body still compiles), and the # ANCHOR: markers drop the _solution suffix the solution uses. Solving a puzzle should therefore only ever add lines.

When you change a solution (for example, migrating to a new API), update the matching problem skeleton the same way. Two checks guard this (both run in CI):

pixi run check-skeletons    # problem == solution outside the fill-in regions
pixi run compile-problems   # every unfilled skeleton still compiles

(problems/p10 is intentionally exempt — it is the sanitizer puzzle, whose skeleton ships deliberately buggy kernels for you to catch with memcheck / racecheck.)

Community

Join our vibrant community to discuss GPU programming, share solutions, and get help!

Acknowledgments

Thanks to all our contributors
Initial puzzles are heavily inspired by GPU Puzzles
Built with mdBook

License

This project is licensed under the LLVM License - see the LICENSE file for details.

_{Built with ❤️ by the Modular team}