Mojo Miji - A Guide to Mojo Programming Language from A Pythonista's Perspective

Community Showcase
1

Hi Magicians,

I have been drafting an online book on Mojo programming language since last summer. With Mojo’s syntax being stabler and stabler, I finally finished most chapters that reflect the features of the latest Mojo version (25.3). It is called “Mojo Miji - A Guide to Mojo Programming Language from A Pythonista’s Perspective”.

The Miji is designed to help Python users quickly adapt to Mojo, highlighting the similarities and differences between the two languages. It tries to provide additional insights, tips, conceptual models that do not present in the official documentation but would be helpful for understanding Mojo from a Pythonista’s perspective, e.g., quaternary system of variable, four statuses of ownership, diagrams of memory layouts for some data structures and operations, etc. Readers can use this Miji as a complementary resource to the official Mojo manual.

The term “Miji” is derived from the Chinese word “秘mì籍jí”, which means “secret book” or “manual”. It is often used to refer to a guide or handbook that provides valuable insights, tips, and shortcuts for mastering a particular subject.

The first four parts of the Miji are summarized as follows.

  1. START: The first part introduces how to set up the Mojo environment on your computer so that you can write your first Mojo program.

  2. MOVE: The second part first shows you how to convert Python code into Mojo code with three examples. Then it highlights the similarities and differences between the two languages. If you are familiar with Python, after reading this part, you will be able to write Mojo code with a certain level of confidence.

  3. BASIC: The third part covers the basic features of Mojo, starting with a conceptual model of variables, and then introducing functions, data types, operators, structs, etc. These features are also present in Python, but Mojo has some differences that you should be aware of. This part will help you to understand the basic syntax and semantics of Mojo.

  4. ADVANCED: The fourth part introduces some more advanced features of Mojo, such as SIMD, parameterization, generic, ownership, etc. These features are not present in Python, but they are essential for writing efficient and safe Mojo code.

  5. MISCELLANEOUS: The final part covers miscellaneous topics, which may be further integrated into the previous parts in the future. This part also includes a glossary of key terms and concepts related to Mojo, as well as a list of information, tips, and warnings that are scattered throughout the Miji. It is particularly helpful if you are already a Magician but want to avoid common pitfalls and mistakes that I encountered while using Mojo.

Although I am continuing working Part V, a case study that implements a matrix struct with Mojo, I still think that it might be a suitable time now to share this Miji in the community, so that more people, particularly Pythonistas, can join in the Mojo world and make Mojo better and popular.

Since Mojo is still evolving, a lot of things in the Miji will be outdated soon. But I will keep it up to date with the latest Mojo version. I will also add more chapters when more functionalities become stable.

Special thanks to you in advance for your feedback!

2

This is really amazing, great work. The upcoming 25.4 release will close a lot of gaps and improve usability in general in Mojo. Please check out the nightlies changelog if you’re interested.

3

Thank you! I will take a deeper look into the changelog for v25.4. A quick glance suggests that quite a few updates will be needed for the book soon :smiley:

4

Great design!

5

This is fantastic.

I only have one small nitpick, which is that we’re trying to get people to use the benchmark module instead of manually timing, since on most systems only timing one operation or one group of operations leaves it vulnerable to the OS scheduler throwing off averages unless you do a very long run. The benchmark module handles that more carefully, while also giving more statistics. Would you be willing to replace the areas you’ve used time.perf_counter_ns() with benchmark.run?

Other than that, this looks like it might be a good version of Rust’s “Rust Book”, but for Mojo.

6

Thank you for your comments and the information on this benchmark module! I will replace the time.perf_counter_ns() with this benchmark.run() in the code on Data type - SIMD. I am curious whether the statistics are different when I use this benchmark.run().

For the comparison between Mojo, C, Rust, and Python on Example Fibonacci sequence, I think manual clocking would be better because I want to keep the code clean so that it is more comparable between languages. After all, it is a very long run (more than 30 seconds). :smiley:

7

For cross-language comparisons, that’s fine, although I also saw that you use a 32 bit int for C and Mojo’s Int is a ssize_t equivalent.

8

Actually, I used int64_t for C in that example, and i64 for Rust.

#include <stdint.h>
#include <stdio.h>

int64_t fib(int n) {
  if (n <= 1) {
    return n;
  }
  return fib(n - 1) + fib(n - 2);
}

int main() {
  for (int i = 0; i < 50; i++) {
    printf("%lld, ", fib(i));
  }
}
9

Chapter References system and Lifetime system are added into the Miji. These chapters may cover some syntax that will be available in v25.4.

10

Hi @forfudan ,

Cool new chapters! One question: Is there a reason you write var ref b = a instead of just ref b = a?

11

Hi @christoph_schlumpf,

Thank you! It is a good question. I wrote this chapter when I was using the 25.4-nightly. I noticed that the ref keyword was not colored if I used ref b = a, so I thought that var ref b = a was a better and more complete syntax to create a reference.

According to the official documentation, the recommended syntax is ref b = a. So I am considering updating this chapter.

Nevertheless, the code var ref b = a also works without error. I am not sure whether this is also a correct way (or the complete syntax) to create a reference (similar to let mut a in Rust). I will keep an eye on this.

12

@christoph_schlumpf , I found that Chris wrote something in the Discord last year September that:

This will also allow defining local references in a nice enough way: var (ref x) = someArray[idx] and depending on how that stacks out, it would be sensible to allow one to just write ref x = someArray[idx]

13

Mojo Miji has been updated to reflect compatibility with the latest Mojo version 25.4. :partying_face:

14

Awesome!

15

The Miji is updated to be compatible with Mojo v25.5 (2025-08-05). The repo for the example programs in the Miji is public now at [GitHub repository](GitHub - forfudan/my-first-mojo-project: Example programs in the book Mojo Miji - A Guide to Mojo Programming Language from A Pythonista's Perspective).

16

The Miji is updated to be compatible with Mojo v0.25.6 (2025-09-22):

  1. Adds a new chapter about copy, implicit copy, and move.
  2. Updates the Chapter on variables and provides more comparisons between Python variables and Mojo variables.
  3. Updates the chapters to accommodate the changes in v0.25.6, e.g., non-implictly-copyable types, deinit keyword, etc.
  4. Fixes typos.
17

This is a really nice update, thank you for working on this! One minor suggestion: your lifetime/origin section could be simplified by introducing ref result types first and basically skirting around Pointer entirely. e.g. near the bottom, instead of introducing:

def shorter(
    word1: String, word2: String
) -> Pointer[String, __origin_of(word1, word2)]:

at all, you could jump right to:

def shorter(a: String, b: String) -> ref [a, b] String:

which is more analogous to the rust code.

We don’t have cycles to invest in the reference system at the moment (preferring to get other parts of the generics system in place) but I would like for Pointer to eventually go away. Today, it is mostly useful for stored pointers, because ref can’t be used in a struct field.

18

Thank you very much for your suggestion! Indeed, the Pointer is more tedious than ref. I will try to update these sections and focus more on refinstead of Pointer . :wink: