This article is Part 5 of our ongoing series on the Mojo programming language. Part 1 introduced Mojo’s origins, design goals, and its promise to unify Pythonic ergonomics with systems-level performance.

Part 2 covered Mojo’s SIMD-first model in practice.

Part 3 covered converting a Python program to Mojo, and exploring how they interact.

Part 4 covered compile-time metaprogramming in Mojo

This article covers

• A review of Mojo’s standard library.

• Creating and importing modules.

• Importing a package from source or compiled.

• Importing external Mojo packages with Pixi.

Our code examples until now were intentionally small, so we almost never needed more than one .mojo file for the source code. When a software project grows bigger, however, it is natural to group related code together in one or more files—for example: helper functions, or data-related structures and methods, and so on.

When this project is meant to execute on its own, it is common to have a main.mojo file as an entry point to the app and as a kind of central hub to oversee the execution. But you can also have code that is only meant to be reused by other projects. These projects typically include APIs (structs with their methods and helper functions) to be imported and used in other Mojo programs, as a library.

This modular design not only helps to structure a project and organize its code, it also promotes code reuse. A similar concept exists in almost all programming languages, with slightly different rules and functionality, and diverging names such as package (Java, Go), assembly (C#, .NET), library, or module. This last name is also adopted in Mojo and Modular software. Mojo also uses the term package as a group of related modules.

Moreover, we want our application to be able to import functionality from other modules, namely from the stdlib, other local Mojo modules, or external Mojo modules written by other people or companies.

We’ve already seen how to import and use local Python modules or external Python packages like numpy in one of the previous articles.

In this article, we’ll discuss how to make and use modules to structure code. This system is quite simple and works a lot like Python. We’ll give an overview of Mojo’s stdlib and see how to import local code and external modules. We’ll also see how Mojo’s packaging system works, compiling module code into binary packages, which can then be imported into our projects.

Finally, we discuss the role of Pixi as Mojo’s package manager.
But we’ll start with what we know already: how to import functionality from the stdlib.

To follow along, use Pixi to create a project called modules_and_packages and cd into it. All code examples used in this article can be found in the code repo here.

Using Mojo’s standard library

Importing functionality from the standard library (stdlib) is so common that we’ve already done it tens of times. For example:

from collections import List
from python import Python, PythonObject
from random import seed, random_ui64
from sys import argv, exit
from testing import assert_equal

Let’s now get an overview of the stdlib.

The standard library is batteries included: it tries to provide everything you need as general functionality in Mojo programming. At the time of writing, it contains some 28 packages (and many more submodules), ranging from algorithm to utils. It implements basic data types like Float32 and SIMD, collection types like List and Dict, reusable functions and algorithms, and modules for GPU programming. Their number and contents still grow quite often, but a good starting point is the overview you can find here.

The Mojo stdlib is organized in packages, each package grouping one or more related modules, for example:

• The algorithm package groups the functional, memory, and reduction modules.

• The memory package contains as important submodules memory, span, arc, owner_pointer, pointer, and unsafe_pointer.

Modular has open-sourced the code of the complete Mojo standard library. Here are the current packages and what they contain or implement (you can look at their source code here):

• algorithm: higher-order functions and SIMD reduction.

• base64: functions for base64 encoding strings.

• benchmark: used for runtime benchmarking.

• bit: functions for bit manipulations.

• buffer: utilities for buffers and DimList.

• builtin: implements core types, traits, and functions, such as Int, Bool, abs, min, max, and many others. It is a comprehensive package of core language features. Not everything in builtin is automatically available in every Mojo program. You may need to explicitly import what you use.

• collections: the string package, and modules for List, Dict, Set, and so on.

• compile: utilities for compiling and inspecting Mojo code at runtime.

• complex: types and functions for working with complex numbers.

• gpu: low-level programming constructs for working with GPUs.

• hashlib: various hashing algorithms.

• json: a high-performance JSON parser.

• logger: logging functionality.

• math: mathematical constants and utilities.

• memory: memory utilities, pointer types, and the Span type.

• os: operating-system dependent utilities.

• pathlib: contains Path and related functions.

• pwd: access to user and group information from the password database.

• python: using Python within Mojo.

• random: functions for generating random numbers.

• runtime: the runtime package.

• stat: aliases and functions for modes like devices, files, sockets, and symlinks.

• subprocess: for running a command.

• sys: interactions with execution and system environment, foreign function interface (FFI), host target info, and intrinsics.

• tempfile: temporary file functionality.

• testing: testing functionality.

• time: basic utilities for working with time.

• utils: numerics functionality, IndexList, StaticTuple, Variant, Writer, Writable.

If you look up the memory package, for example, you’ll see that a package is just a collection of Mojo source files (modules) in a directory that includes an __init__.mojo file, which can be empty.

By organizing modules together in a directory, you can then import all the modules together or individually. The directory name works as the package name when importing the package.

The prelude is a special module that enumerates a set of entities (types, aliases, functions, from builtin and elsewhere) that are automatically available in every Mojo program. You can find them here.

Now we’ll analyze the import syntax, which not only works for the stdlib, but also for local and external Mojo modules.

The import syntax

You probably noticed that module and package names are written in all lowercase, like in Python. To import functionality (data structures or functions), for example from the memory package, use the following code (see import_syntax.mojo):

from memory import memset, memcpy, UnsafePointer

This enables us to use the functions memset and memcpy, or the struct UnsafePointer directly, without having to qualify it with memory:

var lst = List[Int](1, 2, 3)
_ = UnsafePointer(to=lst)

If you look a bit closer, you might notice something strange. The memset and memcpy functions are defined in a memory submodule of the memory package. Shouldn’t we import them as:

from memory.memory import memset, memcpy

This works also, but the shorter version from memory import memset, memcpy works because the __init__.mojo file that is also read in when importing memory contains the line:

from .memory import memcmp, memcpy, memset, memset_zero, stack_allocation

(.memory refers to the submodule memory in the current folder.)

The __init__.mojo file in a package re-exports, as it were, the contents of the submodules to the package level. (Now explain why we don’t need to write from memory.unsafe_pointer import UnsafePointer.)

If you want explicitly to import from a submodule, write:

from max.engine import InferenceSession

To avoid name-clashes, or simply to shorten the name, you can use as to define an alias for the thing you are importing, for example:

from memory import UnsafePointer as UPt

You can then use it in code as:

_ = UPt(to=lst)

The general syntax is:

• from package1 import function1, Struct1

• or: from package1.submodule1 import function2, Struct2

To import all definitions, it is possible to use:

• from module1 import *

• or simply: import module1

But doing this is considered a bad practice: only import what you really need to use less resources. That way you also know to which module a certain function or struct belongs.

For the same reason, when using the syntax import module1, it is idiomatic to qualify the functions or structs with the module name, like this:

import memory
_ = memory.UnsafePointer(to=lst)

Or use an alias like this:

import memory as mem
_ = mem.UnsafePointer(to=lst)

You cannot import the same module more than once. If you do, you get this kind of error:

invalid redefinition of 'memset'

If you have many things to import, enclose them within (), like this:

from sys.info import (
    alignof,
    sizeof,
    bitwidthof,
    simdwidthof,
    simdbitwidth,
    simdbytewidth,
)

from/import statements can be written everywhere in code, but code clarity can be enhanced by grouping them at the start of a code file. Writing them in alphabetical order is also advisable when there are many import lines.

Making and importing a Mojo module

A Mojo module is just a single Mojo source file that includes code (like an API), suitable for use by other files that import it. The source file name is also the module’s name. It doesn’t need a main() function, because it is not meant to be started on its own: the program that imports the module will usually contain a main() function to start the application.

The module gets its name from the source file name, without extension. For example: a file compute.mojo contains the code for module compute. Let’s reuse a previous example, rewriting the Python module as a Mojo module compute:

fn mul(n: Int, m: Int) -> Int:
    return n * m

fn pow(n: Int, m: Int) -> Int:
    return n ** m

Now we can import this module (or part of its functionality) in a source file (see main.mojo) in the same folder which can execute:

from compute import mul, pow     #A

fn main():
    var i = 42
    var j = 7
    var res1 = mul(i, j)         #B
    var res2 = pow(i, j)         #B
    print(res1, res2)  # => 294 230539333248

#A Import functions mul and pow from compute
#B Call functions mul and pow from main.mojo

Importing the mul and pow functions from module compute and executing them in a program could not be easier. The folder structure is:

/project_folder
    main.mojo       #A
    compute.mojo    #B

#A The main program
#B The local compute module

Common file structure for a project

From Appendix A (found at the end of this article) we can learn what the most basic structure of a Mojo project is after creating it and installing the Modular environment:

/project_folder
    .pixi/          #A
    .gitattributes  #B
    .gitignore      #B
    pixi.lock       #C
    pixi.toml       #D

#A Folder with the virtual environment
#B Files needed for a GitHub project
#C Contains versions for all dependencies (auto-generated)
#D The project configuration file

The directory project_folder is also called the project root folder. pixi.toml is the project configuration file, or manifest. It is generated by the pixi tool but can be edited afterwards.

In Figure 10.1 you see an example project structure based on official documentation and community best practices.

Key points:

• A Mojo project is by default a local repository, ready to be published in a GitHub repo online.

• The pixi.toml and pixi.lock files are created and managed by the Pixi CLI and define your project’s dependencies and environment.

• The .pixi directory contains the virtual environment for the project.

• Each Mojo package is a directory with an __init__.mojo file to signal it’s a package. Modules (e.g., module1.mojo) live inside these package directories.

• You can organize Python code in a separate directory (e.g., py/) if your project uses both Mojo and Python.

• A tests directory is commonly used for test files, and sometimes a link to the code directory is used to simplify imports during testing.

This structure is flexible and can be adapted to your project’s needs, but the presence of pixi.toml, .pixi, and init.mojo files in package directories is essential for proper project- and package management by Mojo and Pixi.

The project’s app starts running with main.mojo, which imports code from package1 and uses it.

Fig. 1 – Typical project folder structure. In our example, package1 would be compute.
In general, when there are more packages than package1, they can exist parallel to each other, or all be subfolders of one folder src.

Importing a package from source files

Let’s now reorganize our project to this structure, calling it compute_project.
In our folder modules_and_packages do:

$ pixi init compute_project -c "https://conda.modular.com/max-nightly" -c "https://repo.prefix.dev/modular-community" -c "conda-forge"
✔ Created /$HOME/mojo_book/modules_and_packages/compute_project/pixi.toml
$ cd compute_project
$ pixi shell

Now the current Modular virtual environment is installed, and you can check the Mojo version with:

$ mojo -v
# => mojo 25.4.0.dev2025052116 (fb591a52)

Copy the file main.mojo to folder compute_project. In it, create a folder compute, and move compute.mojo in it. But if we now try to run the program, we get an error:

$HOME/mojo_book/modules_and_packages/compute_project/main.mojo:1:6:
error: unable to locate module 'compute'
from compute import mul, pow
     ^

The reason is that folder compute is not recognized as a package. To remedy that, it needs a (possibly empty) __init__.mojo file, so we create this. The folder structure of compute_project has now become:

Fig. 10.2 – Folder structure of compute_project

Now the package compute is recognized, but we still get an error when trying to run:

error: package 'compute' does not contain 'mul'
from compute import mul, pow

This means Mojo doesn’t find the mul function. What’s still needed is to expose the functions from the compute module in the __init__.mojo file as follows:

from .compute import mul, pow

This is called re-exporting the module’s symbols: .compute here represents the local (.) compute module. Such relative imports only work inside packages.

This makes your APIs (like mul and pow here) accessible from the package name compute.
What we have done can be called importing modules to the package scope.

Here you could decide not to expose functions or structs that are private to the modules, such as pure helper functions. The names of private functions or structs start with an _.

We finally get the correct results:

$ mojo main.mojo
# => 294 230539333248

Here the package and module are both named compute, but this could be different, especially when there are several modules in the package.

An alternative way is to leave __init__.mojo empty. Then you have to write the import in main.mojo in the qualified form package.module as:

from compute.compute import mul, pow

The presence of __init__.mojo is crucial here. If you delete it, then Mojo doesn’t recognize the directory compute as a package and it cannot be imported. So, a Mojo package is a directory containing an __init__.mojo file (which can be empty). This tells Mojo to treat the directory as a package.

Nested packages (subfolders with their own __init__.mojo) can also be used, just like in Python. This allows you to organize your code hierarchically.

Instead of importing from source files, we can also make a binary package, as we’ll see now.

Importing a compiled package

A more efficient way to work with packages is to compile the package into a .mojopkg or .📦 file. That’s easier to share than a bunch of source files, while being still compatible with other system architectures. Moreover, compiling module code into binary packages will get you faster start-up and execution.

Compiling a package

Compile a package’s package1 source code into a package file with the mojo package command like this:

mojo package package1 -o package1.mojopkg

package1.mojopkg is the name of the output binary.
In our example this would become:

mojo package compute -o compute.mojopkg

This creates the package file compute.mojopkg.

The code in a .mojopkg file is parametric bytecode, obtained by compiling Mojo source code with the JIT part of the compiler.

The filename which you specify with the mojo package command can differ from the package directory name. Be careful what you use as the package name in the from package import … statement:

• When importing from source files, the directory name must be used as the package name.

• When importing from a compiled package, the filename (without the .mojopkg extension) is the package name.

To specify a new name, simply run mojo package again with the new output name. Make sure that the name of the package file and the imported name in main.mojo stay the same.

Now the user doesn’t need to have the source code on their machine anymore. The package code can be moved elsewhere (say into a folder production), and the project structure looks like this:

/production
    compute.mojopkg
    main.mojo

Executing mojo main.mojo still produces the same output.

Building the project

If you want to get rid of the binary package file as well and compile everything into one executable app, use the command:

mojo build main.mojo -o app

Then ./app gives the same output as before, even when the .mojopkg file is removed.
Now your project can be distributed in only one file:

/production
    app

Test this by copying the app file in a completely different folder and execute ./app to see the same output (you probably will have to do a chmod u+x app).
Note that when building, the binary code becomes architecture specific.

Using pixi as Mojo’s package manager

Currently many external modules are being written by members of the Mojo community. The official repository for these modules is located here.

The modules published there are being reviewed and must contain a test suite to ensure their quality. You can also view the featured community packages in a more readable format here.

Whether you want to install, submit, or review packages, this forum post can get you started.

The pixi tool that we know from installing the Modular environment (see Appendix A found at the end of this article) is also used to install modules from this repo into your local environment. To follow along, make sure you’re in the modules_and_packages folder, and after typing pixi shell, you get the following prompt:

(modules_and_packages) user@computer:~/mojo_book/modules_and_packages$

As an example, we will install the lightbug_http package. Execute the following steps:

1. Add the Modular community channel (https://repo.prefix.dev/modular-community) to your pixi.toml file in the channels section:

[project]
authors = ["Author data"]
channels = [
  "https://conda.modular.com/max-nightly",
  "https://conda.modular.com/max",
  "conda-forge",
  "https://repo.prefix.dev/modular-community",
]
name = "modules_and_packages"
platforms = ["linux-64"]
version = "0.1.0"

[tasks]

[dependencies]
max = "*"

2. Pixi allows you to browse for packages from the above channels by typing pixi search light* on your command-line:

$ pixi search light*
Using channels: https://conda.modular.com/max-nightly/, https://conda.modular.com/max/, conda-forge, https://repo.prefix.dev/modular-community/
Package                                  Version             Channel
lightly                                  1.5.20              conda-forge/noarch
lightfm                                  1.17                conda-forge/linux-64
…
lightbug_http                            0.1.19              https://repo.prefix.dev/modular-community//linux-64
…

3. To install the chosen package, enter the following command:

$ pixi add lightbug_http
V Added lightbug_http >=0.1.19,<0.2

Verify with the pixi list command that the package is installed locally in your project.

4. From here you can import any functionality you need from the package with import statements as previously discussed, for example:

from lightbug_http.service import HTTPService

Appendix A

Setting up a development environment

Follow the steps below and you’ll start coding with Mojo in no time.
The Mojo tools are completely free forever and will eventually be open-sourced.

NOTE
Currently, the Mojo toolchain works on Linux (Ubuntu and other distros) and on macOS (Apple Silicon). On Windows, everything works fine within the WSL2 environment. Native support for Apple (Intel) and Windows is coming.

A.1 Installing Pixi

Installing Mojo locally is a quick and easy process. We only need to get pixi and the modular package.
Use the following command from a terminal if pixi doesn’t exist yet on your machine:

$ curl -fsSL https://pixi.sh/install.sh | sh

Now the pixi binary is in the folder $HOME/.pixi/bin, where $HOME equals /home/username or ~, and the command is system-wide available.

Test it by showing its version:

$ pixi -V

Output, for example:

pixi 0.48.0

If you need to get the latest version, do:

$ pixi self-update

Removing pixi is as easy as:

$ rm ~/.pixi/bin

$ pixi -h shows all available commands.

NOTE:
If you’re working in a newly created Linux/macOS or WSL environment, make sure to install:

$ sudo apt-get install -y git gcc g++ zlib1g-dev libtinfo-dev

What is Pixi?

Pixi is a virtual environment manager and works also as package manager for Mojo, Python, and other languages, kind of like what cargo is for Rust developers.

Why use a virtual environment?

Pixi allows you to create fully contained projects in a so-called virtual environment (venv), which is a separate environment (in a folder) which contains the exact versions of all packages you need.

In a venv, the package dependencies and environment settings are automatically managed for you. In fact, any Mojo project is created in a virtual environment. What is the advantage of working with this? In the global (machine-wide) environment, you can have only one version of a package installed, say numpy v 2.0. Suppose you need to maintain a project which uses numpy v 1.8. This cannot work globally, so you have to create a closed virtual environment containing numpy 1.8, in which you can maintain your project. This venv can contain particular versions of Mojo and of any package your project needs. Now you can work on your project without any conflicts with the global environment or any other virtual environments you create.

Let’s illustrate this more concretely by creating a Mojo project.

A.2 Creating a Mojo project

To keep all your Mojo projects in one place, you probably want to create a folder (any name will do) like mojo_projects, and cd into it.

The following command creates a Mojo project named project1 with pixi init:

$ pixi init project1 -c "https://conda.modular.com/max-nightly" -c "https://repo.prefix.dev/modular-community" -c "conda-forge"

This displays the following output:

Created $HOME/mojo_projects/project1/pixi.toml

A folder project1 is created, git version control-ready (cd into it and check with $ ls -al). It contains the configuration file (also called the manifest) pixi.toml, which contains:

[workspace]
authors = ["Username <email-adress>"]
channels = ["https://conda.modular.com/max-nightly", "https://repo.prefix.dev/modular-community", "conda-forge"]
name = "project1"
platforms = ["linux-64"]
version = "0.1.0"

[tasks]

[dependencies]

The channels field in [workspace] contains all locations where pixi can find and download the files that are necessary to run your Mojo code.

In the [tasks] section, you can define different tasks to be executed for your project, like testing. The [dependencies] section names the versions of all packages your code depends on.

Note
In the pixi init command we used the channel "https://conda.modular.com/max-nightly". This gives you the nightly update of the Modular package and Mojo compiler, containing the latest new features and performance improvements. If you want to stay in sync with the rapid development of Mojo, this is ok. Be warned that this version can be unstable, and changes very frequently, so this is not to be used for a project in production!
On the other hand, if you want to stay synchronized with a stable version of Mojo, say v. 25.4, you should use the channel "https://conda.modular.com/max" instead.

With this setup, Mojo works only inside the directory created with pixi init, which is great for project development. If you want the latest stable Mojo to be system-wide available, you can install it globally with:

$ pixi global install max -c conda-forge -c https://conda.modular.com/max/ --expose mojo

If you want to create a pixi project in an existing folder, just go into that folder and issue the previous command, leaving out the project name project1.

Installing the Modular platform

This can be done in two ways:

1. Execute the command:

$ pixi add modular

This downloads and installs the modular package in your folder. When it is finished, it displays:

✔ Added modular >=25.4.0.dev2025060721,<26

Check that this dependency was added to the pixi.toml file!
The MAX engine, which is registered as a conda project, is now installed. Mojo is bundled together with MAX, so it is available as well!

The command also has added the following:

• A .pixi subfolder, which contains the complete virtual environment for your Mojo project in the folder envs.

• A pixi.lock file

This big file contains in detail all dependencies, namely the exact versions and the dependencies of the dependencies (the transitive dependencies). This ensures that you get the exact same environment when building your project on another machine.

If you’re curious, look inside it with the grep command: grep -R 'word' pixi.lock, for example: grep -R max pixi.lock.
Do not edit/change it, because this is an auto-generated file!

Let’s verify the Mojo version we have installed in our project environment with the following command (pixi run executes a command in the venv):

$ pixi run mojo --version

This should display something like:

Mojo 25.4.0.dev2025060721 (b35d3649)

Where devnnn denotes the latest Mojo nightly file.

2. Another way to install the platform is by editing the pixi.toml file, and adding a line to the [dependencies] section of the format "package = version", in our case:

max = "*"

The max package contains the mojo package, so this gets us Mojo as well. "*" means: get the latest (nightly) version.

The version could also be indicated as:

• "==25.4": which gets you that exact version.

• ">=25.4": meaning, install the latest version in “any version from 25.4” or later.

• ">=25.2, <25.4": meaning, install version 25.2 or later, but less than 25.4.

• "~=25.4": this adds a version of Max and Mojo, namely v25 and compatible versions.

When this info is saved, run the following command in a terminal:

$ pixi install

Both ways will add this dependency info also to the pixi.lock file.

NOTE:
In a future version, the subfolder .pixi will contain all dependencies not physically as it does now, but as links. Only one copy of every version of every dependency is kept on your machine in a system cache, and each project only links to the copies it needs.

A.3 Working with the pixi shell

You can run a Mojo program outside the pixi shell with:

$ pixi run mojo hello_world.mojo

But it is much easier to work inside the shell using simpler commands. To enter this shell do:

$ pixi shell

This will show you a new prompt, which starts with your project name, like:

(project1) username$computername: folder-path$

Now you can work with any mojo command. For example, check the version of Mojo and MAX with:

$ mojo -v

mojo 24.6.0 (4487cd6e)

Use exit to leave the pixi shell to the OS prompt.

Some other useful Pixi commands

Here are some of the most used commands:

1) Add a dependency

This is done through the add command. For example, to add a specific Python version to your Mojo project you can use:

$ pixi add "python==3.10"

Try it out and examine the change in the .toml configuration file.
Use the same command to add one (or more) Python packages:

$ pixi add "python==3.10" "numpy<2.0"

This adds python v 3.10 and the latest version of NumPy that’s less than 2.0.

An alternative way is to add these dependencies to pixi.toml as:

python==3.10
numpy<2.0

and then run pixi install again.

If the package is not available in conda-forge, you must add its channel to the channels list in pixi.toml.

2) Update a dependency

Use the pixi update packagename command, for example:

$ pixi update max

3) Clean the local project environment

The command pixi clean will delete the current environment, without affecting the manifest .toml file.
pixi install then installs the latest versions. The neat effect is to remove any outdated dependencies. This avoids clutter and keeps your project running fluently.

4) Starting from a Python project

Add the desired Python version to the project folder with:

$ pixi add "python==3.12"

How would you add Mojo to such a project?
Run:

$ pixi add max

For more details on what Pixi can do, see chapter 10 and the official documentation (https://pixi.sh/latest/getting_started/).

You can also install the Modular software as a Python package in a Python environment with:

$ pip install modular

(https://docs.modular.com/max/get-started/)

A.4 Installing Visual Studio Code, the Mojo extension and Jupyter notebooks

Plugins exist for the vim and PyCharm editors, but the most popular development platform for Mojo is Visual Studio Code (VS Code) (

https://code.visualstudio.com/

). Installing this is straightforward. It works on every OS; notably, the Windows integration with WSL2 is superb.

Then install the official plugin (developed and maintained by the Modular team) called vscode-mojo from:
https://marketplace.visualstudio.com/items?itemName=modular-mojotools.vscode-mojo
or search for “Mojo” in the “Extensions: Marketplace” tab.

Together with its integrated LSP (Language Server), it gives you a ton of functionalities.

Note
Two versions of the extension exist: Mojo and Mojo (nightly). The first one is the stable version. Synchronize this with the version you use in your Mojo projects.

We’ll start using it in § 1.4.2.
The Mojo LSP server can also be used in other editors that support LSP.

To work with Jupyter notebooks in VS Code, you need to install the Jupyter VS Code extension from:
https://marketplace.visualstudio.com/items?itemName=ms-toolsai.jupyter

Here are the steps to install Jupyter notebook in a project:
Within your pixi shell, add Python with, for example:

$ pixi add "python==3.12"

Then run the command:

$ pip install notebook

For Mojo you need to install the following libraries:

$ pixi add ipykernel jupyterlab

A.5 Moving from magic to Pixi

In an existing magic project:

• do magic clean

• delete the .magic folder and magic.lock

• rename mojoproject.toml to pixi.toml

• do pixi install

A.6 Where to find more information

For more information, you can access the GitHub repository for Mojo and Max or the official docs.

You can also contact other Mojo users or the Modular team on the Discord channel or on the Forum. Discord even has an AI-chatbot specialized in Mojo code to answer your queries or problems. Just type @kap and choose the value @kapa.ai from the list, then state your question after that (see the channel mojo-bot-help).

A Reddit channel and a community website are also available. For broader info, you can consult Modular’s website.

The MAX Builds page is also live and contains examples of implemented AI models, recipes, and top community packages, which you can view here. Their official repo is maintained here.

An overview of educational material and links to community projects can be found here.

Info about local installation:

The pixi executable is stored centrally at: $HOME/.pixi/bin

Currently (June 2025) a project’s dependencies are still physically contained in the .pixi folder of every project (more precisely in $HOME/projectname/.pixi/envs/default/):

• The mojo cache and modular.cfg file is stored in the subfolder share/max.

• The mojo, mojo-lldb, and mojo-lsp-server executables are stored in the bin subfolder.

• The Mojo/Max packages are stored at the lib/mojo subfolder.

© 2026 Ivo Balbaert. All rights reserved.

This article is Part 4 of our ongoing series on the Mojo programming language. Part 1 introduced Mojo’s origins, design goals, and its promise to unify Pythonic ergonomics with systems-level performance.

Part 2 covered Mojo’s SIMD-first model in practice.

Part 3 covered converting a Python program to Mojo, and exploring how they interact.

In this article, we will discuss Mojo’s possibilities to do metaprogramming, which is possible at compile time. Let’s first explain what we mean by metaprogramming.

To follow along, use pixi to create a project called comptime, cd into it, and start a pixi shell.

All code examples used in this article can be found in the code repo here and here.

What is metaprogramming and why is it important?

Metaprogramming is about transforming or generating code at compile time. The new or changed code is then compiled and executed at run time.

One of the great characteristics of Python is that you can change code at run time—so-called run-time metaprogramming. This can do some amazing things, but it comes at a great performance cost.

The modern trend in programming languages is toward statically compiled languages, with metaprogramming done at compile time. Think about Rust macros, Swift, Zig, and Jai. Mojo, as a compiled language, fully embraces compile-time (comptime) metaprogramming, built into the compiler as a separate stage of compilation—after parsing, semantic analysis, and IR generation, but before lowering to target-specific code. To do this, the same Mojo language is used for metaprograms as for run-time programs, and it also leverages MLIR. This is because work in AI needs high-performance machine learning kernels and accelerators, and high abstraction capabilities provided by advanced metaprogramming systems. You can also write imperative compile-time logic with control flow, even compile-time recursion.

Currently, the following techniques are used in Mojo to do metaprogramming:

• Defining aliases at comptime. These are constants, so they won’t change during the execution of the program.

• Running arbitrary Mojo code at comptime to set parameter values with an alias.

• Checking a function constraint at comptime with a constrained statement.

• Using the decorators @parameter for and @parameter if to run the for and if loop they mark at comptime. The for-loop is unrolled at comptime and the if-condition is checked at comptime, so that code is only generated for the branch that evaluates to true. Use @parameter to make a function run at comptime and turn it into a parametric closure.

• Using @always_inline to force a function to be always inlined. The body of the function, with parameter values inserted, is then placed at the function call site.

• Functions and structs with overloading on parameters: using parameters in functions to transfer part of the computation to comptime, so that execution time is reduced.

• All Python processing happens at comptime; that is, all interaction between the Python interpreter and the Mojo compiler happens at comptime. Python code is processed at comptime by the CPython interpreter.

• Note that memory used by Mojo is not freed by a process at run time like a garbage collector (GC). Instead, the Mojo compiler, while analyzing how data is manipulated through code, inserts the code to free memory in the executable during comptime.

So we see that a lot of preparation and processing can be done at comptime, leading to speed gains at run time. For example: a function can be executed at comptime and keep its results for use at run time.

We’ll explore examples of these techniques in the rest of the article, but first let us clear up the difference between comptime and run time.

Compile time and run time

Python, being interpreted, has only one phase, namely run time: it is interpreted while it is running. But Mojo, as a compiled language (with mojo build), splits compilation from execution, so it has two phases:

• Compile time (abbreviated to comptime) is when the compiler scans your program and generates errors or warnings. If no errors are found, an executable (containing machine code) is generated. Data that is known at comptime is said to be statically known.

• Run time is when the executable runs on your machine. Often, data is not known at comptime, but only at run time—for example, when it is read in from a network or calculated with input during execution. Such data is said to be dynamically known.

Mojo code can also run at compile time, following the trend in many other modern statically compiled languages.

Everything that can be done at comptime has a performance benefit because it saves run time. This is a form of metaprogramming, which is extensively used in Mojo. Python can also do metaprogramming, but only at run time. Mojo can simulate some types of dynamic programming, but it can do a lot more as well.

Now we’ll show example code using some of these techniques.

Aliases and running functions at comptime

Executing code at comptime is one of the key aspects of Mojo’s performance. It lowers the amount of code to be executed at run time. This can be done in a flexible way: functions can be annotated with decorators such as @parameter if and for to make them run at comptime and preprocess the code to execute.

When the argument values of a function are already known at the time of writing the code (and thus also at comptime), we might as well execute the function at comptime, saving the results in the executable for use at run time. Think of doing a complex calculation or building a data structure and shaving off quite a bit of the execution time!

As we saw in Part 1, an alias can be defined like this:

alias SUM = sum(10, 20, 2)  # A

fn sum(lb: Int, ub: Int, step: Int) -> Int:
    var total = 0
    for i in range(lb, ub, step):
        total += i
    return total

fn main():
    print(SUM)               # => 70
    print(sum(10, 20, 2))    # => 70      # B

#A SUM is calculated by executing the sum function at comptime.
#B The same sum is calculated at run time.

An alias is a comptime constant. A variable, on the other hand, exists only at run time and has a limited lifetime (scope) in which it is known.

The right-hand side of an alias declaration is executed at comptime. The line print(SUM) compiles to the code print(70), which is displayed at run time. The result is that there is less to compute at run time, which makes the code more performant.

The function sum can be used both during comptime and run time. The alias SUM ensures that the calculation is done at comptime, making it usable at run time. The result is stored as an alias constant in the executable file. This means that when the program is run, it just takes the alias constant.

Aliases are used a lot in code, also as fields inside structs and traits. They can even be used to set a type at compile time, like this:

alias dtype = DType.float32

The way DType is used here creates specialized code at comptime, optimized for the type Float32.

Not every function can be run at comptime, however. To be able to do that, the function must be:

• an fn-type function (so a def function cannot be run at comptime);

• a pure function. Such functions have no side effects; that is, they can only use the arguments passed to them and cannot change any variables or state outside of the function body.

Functions can also be conditionally executed at comptime, either by testing known or computed alias values or checking whether a certain name is defined at the command line.

Conditional execution at comptime

A function at comptime can also be called conditionally using an if/else test on values that are known at comptime. Working further on the example of the previous section, let’s replace the line alias SUM = sum(10, 20, 2) with the following code (see alias_calc_condition.mojo):

alias lb = 10
alias ub = 20
alias step = 2
alias SUM = sum(lb, ub, step) if lb < ub else 0   # A
# A Call of sum() at comptime is dependent on the values of lb and ub

Now the sum function will only be called when the condition lb < ub is met. Replace the value of lb in the above code with 50, and see that SUM now becomes 0 instead of 70.

Another trick is to make the comptime execution of a function dependent on a command-line variable provided with -D. In the following version (see alias_calc_conditionD.mojo) we start the program with:

$ mojo -D calc_sum alias_calc_conditionD.mojo

The result for SUM is still 70. The functions main() and sum() remain the same, but now the alias condition is changed to:

from sys import is_defined       # A

alias lb = 10
alias ub = 20
alias step = 2
alias SUM = sum(lb, ub, step) if is_defined[”calc_sum”]() else 0  # B
# A The function is_defined is imported from the sys module
# B is_defined is called here: this tests if a variable calc_sum is defined on the command line

The line is_defined[”calc_sum”]() checks whether a command-line variable calc_sum is provided after the -D option flag. Only then is the function sum(lb, ub, step) called.

The more info a function can get at comptime, the more useful its execution at comptime becomes. Mojo introduces parameters for that purpose: they are used at comptime, in contrast to function arguments which are used at run time.

Mojo function parameters work like arguments, but they must be known at comptime. They also allow for more generic and flexible functions. Understanding parameters is one of the secrets any upcoming Mojo developer must master: they are pervasive in stdlib code and commonly used in heavy calculations. Let’s dig deeper into them.

Using parameters in functions

Another powerful tool for running functions is comptime parameterization. This technique (that originated in Zig) uses a list of parameters provided between [] in the function header. These parameters must be (or reduce to) constant values at comptime and are used inside the function’s code. Using them, the compiled code for the function can be simplified, so that run-time execution performs better. We will start with a simple parameter example.

A function with a parameter

In Listing 1, we see a greet function that prints out a message variable one time. Suppose we want to greet several persons at the same time. Using a for-loop around greet would be an obvious solution, and we can pass the number of greetings as a variable count, as we’ve done in fn greet_repeat_args. But an alternative is to pass count as a parameter between [], as we’ve done in fn greet_repeat[count: Int](msg: String) (see fn_param.mojo):

Listing 1 — A function with a parameter

fn greet(msg: String):
    print(msg, end=” / “)

fn greet_repeat_args(count: Int, msg: String):  # A
    for _ in range(count):
        greet(msg)

fn greet_repeat[count: Int](msg: String):       # B
    for _ in range(count):
        greet(msg)

fn main():
    greet(”How are you?”)
    print()
    greet_repeat_args(3, “Hello there!”)        # C
    print()
    greet_repeat[3](”Hello there!”)             # D

# =>
How are you? /
Hello there! / Hello there! / Hello there! /
Hello there! / Hello there! / Hello there! /

#A The function greet_repeat_args has two arguments count and msg.
#B The function greet_repeat has a count parameter between [].
#C Arguments are passed between ().
#D The parameter count’s actual value is passed between [].

The output is the same, so why bother? Everything passed to a function between [] is a compile-time parameter (like count in our example). This parameter becomes a run-time constant. The compiler makes a specific version of greet_repeat with the count value set to 3, like this:

fn greet_repeat(msg: String):
    for _ in range(3):
        greet(msg)

which is then compiled and executed at run time. You can see that the parameter presets a value in the code. The code for fn greet_repeat_args is more complex at run time than greet_repeat, because it still must process two arguments. In this simple example, this doesn’t visibly influence performance, but for complex functions with many parameters these preset values may make a big difference in run-time execution—specifically when the parameter contains a type as value: then the run-time code can be optimized for that type.

(Note that the iteration variable in the for-loop is written as _; we don’t need to create a variable here because it is not used in the loop’s body.)

Now we know that Mojo can do computations at two different times of execution: comptime and run time, and data can be used at comptime or at run time:

• Parameters (enclosed between []) are processed at comptime and become a static (constant) value to be used at run time.

• Arguments (enclosed between ()) are processed at run time and become a run-time (or dynamic) value.

A function header schematically looks like this:

fn fun_name[parameter_list](argument_list) -> return_type:

The parameter list is optional as well as the return type, and the argument list can be empty.

Parametric code gets compiled at comptime, not JIT-compiled (Just-In-Time compiled) at run time. Multiple specialized versions of the code are generated, parameterized by the concrete types used during program execution.

In general, if you encounter the error cannot use a dynamic value in a type parameter, this means that you used a run-time value as a compile-time parameter.

TIP

The word parameter has a totally different meaning in Mojo than in most other programming languages, where the defined versions of a function’s arguments in its signature are called the function’s parameters. For example, in this Java function header: public int add(int a, int b), int a and int b are called the parameters of function add. When the function is called, like in add(3,5), 3 and 5 are the arguments. In contrast, in Mojo, parameters are comptime values, and arguments are run-time values.

Parameters also can have default values, for example: fn greet_repeat[count: Int = 2](msg: String). Just like variadic arguments, you can pass a variable number of parameters like this: fn add_all[*a: Int]() -> Int, which can be called as: add_all[1, 2] or add_all[1, 2, 3, 4, 5] or add_all[].

The @parameter for decorator

By adding a @parameter decorator, we can significantly improve performance by evaluating the for-loop entirely at compile time. In the function greet_repeat in the previous example, the range was known at comptime through the parameter, but the for-loop itself still had to be executed at run time, like this:

fn greet_repeat(msg: String):
    for _ in range(3):
        greet(msg)

Mojo can do better: by prefixing the loop with the @parameter decorator like this:

fn greet_repeat(msg: String):
    @parameter                  # A
    for i in range(3):
        greet(msg)
# A The @parameter for decorator unrolls the for loop

Now, the loop will be unrolled. It will be changed to a sequence of statements at comptime as:

fn greet_repeat(msg: String):
    greet(msg)
    greet(msg)
    greet(msg)

This might not seem spectacular here, but when used in complex and nested for-loops, it can have massive implications for run-time speed, like in this code snippet:

@parameter
for i in range(NUM_BODIES):
    for j in range(NUM_BODIES - i - 1):
        var body_i = bodies[i]
        var body_j = bodies[j + i + 1]

A downside of unrolling loops is that the program grows in size before it is compiled, resulting in a slightly increased compilation time and executable size.

Checking constraints to which functions must comply to run is important to make your code robust. This can be done at comptime with constrained testing, or at run time using assert testing. Because this article is targeted to code executed at comptime, we won’t talk about assert testing in detail here, but there is an example of its use in the code example for @parameter if.

Constraints checking in functions

Often, we write programs in which we unconsciously suppose that certain values or arguments comply with certain conditions. In certain edge cases, these conditions might not be met, crashing our program while running, which could get us caught in a long debugging session. Now that we know about parameters, the same situation can happen there: a program can crash with a compiler error during comptime. A compiler error might not be so easy to track down, and debugging metaprogramming at comptime is not nearly as nice as normal run-time debugging. We as developers must arm ourselves against these situations, both during run time and during comptime. Luckily, Mojo has our back in this.

Checking constraints during comptime

A program that crashes because of an incompatible parameter during comptime (while doing metaprogramming) is annoying. When a function has parameters, it would be nice if we could test these parameters on certain conditions. That’s where constraints come in: they are like custom comptime checks you as a developer can add to enhance the robustness of comptime execution.

Suppose we want to make sure that our machine has an NVIDIA GPU at our disposal, running on an Apple M2 or M3 processor. This can be done as shown in Listing 2 (see constrained_checking.mojo):

Listing 2 — Using constrained to test comptime conditions

from sys.info import is_apple_m2, is_apple_m3, has_nvidia_gpu_accelerator

def main():
    machine_checks[]()

def machine_checks[]():
    constrained[has_nvidia_gpu_accelerator(), “No NVIDIA GPU present”]()
    constrained[is_apple_m2() | is_apple_m3(), “Not an Apple M2 or M3 CPU”]()
    # => note: constraint failed: Not an Apple M2 or M3 CPU

Running on a machine which has no Apple M2 or M3 processor, the constraint failed on this condition. However, we got no warning about the GPU, so this computer has an NVIDIA GPU.

Note that constrained has the condition as its first parameter, and the message displayed in case the condition is false as its second parameter.

Other decorators for functions

Decorators are a powerful and elegant feature in many programming languages (Python; annotations in Java; modifiers in C#; and so on) that allow you to modify the behavior of a function, method, struct, or class without changing its source code. Decorators are another form of metaprogramming, since a part of the program (the decorator) tries to modify another part of the program (for example, the function or struct) at comptime.

Decorators are no stranger to us: we encountered @register-passable in previous articles. In Mojo, decorators are higher-order functions, prefixed with @ and placed in front of the function, struct, or code they influence. At comptime, the higher-order function behind the decorator name is called to modify or extend the code they decorate.

In this section, we’ll specifically focus on decorators used for code and functions. In the next section, we’ll discuss decorators for structs.

@always_inline

Inlining a function means taking its code body and replacing the function call with the function body. This improves run-time performance by avoiding function call overhead; it eliminates jumping to a new point in code. But if the function is large and called many times, we have a lot of duplicated code, increasing the program’s binary size.

Normally, the compiler will do inlining automatically where it improves performance. But you can force this behavior with @always_inline: this decorator forces the compiler to always inline the decorated function, directly into the body of the calling function.

In the following example we combine @always_inline with @parameter for (see always_inline.mojo):

@always_inline                          # A
fn print_and_increment(mut x: Int):
    print(x)
    x += 1

fn main():
    var i = 0

    @parameter                          # B
    for j in range(0, 3):
        print_and_increment(i)

# =>
# 0
# 1
# 2
# A @always_inline replaces the function call by the function’s code
# B @parameter for unrolls the for loop

Applying @always_inline removes the code before main(), so that it is transformed like this:

fn main():
    var i = 0

    @parameter
    for j in range(0, 3):
        print(i)
        i += 1

After applying @parameter for, the code is reduced to:

fn main():
    var i = 0
    print(i)  # => 0
    i += 1
    print(i)  # => 1
    i += 1
    print(i)  # => 2
    i += 1

The program is faster by not checking if j < 3 on each iteration of the range and by not having to jump into print_and_increment. It also becomes bigger, but this is a choice you make.

@always_inline is pervasively used in high-performance Mojo code.

There is a variant @always_inline(”nodebug”) which speeds up a bit more by removing the debugging information of the function, so you won’t be able to debug it anymore. Apply this variant to low-level functions which call MLIR or inline assembly code, which you probably won’t or can’t debug.

@parameter if

The decorator @parameter if will make an if statement run at compile time. In our example, it is used to define an alias debug_mode. Only when debug_mode is True will the assertion code be included and run in the final executable (see parameter_if.mojo):

Listing 3 — Using @parameter if to create a debug mode

from testing import assert_true

alias debug_mode = True  # A

fn example():
    @parameter
    if debug_mode:       # B
        print(”debug”)

fn main() raises:
    example()            # => debug

@parameter
if debug_mode:           # C
    _ = assert_true(1 == 2, “assertion failed”)
    # => AssertionError: assertion failed

# A Define debug_mode with an alias
# B Test @parameter if
# C The assert_true will only be included if debug_mode is True

Only when the condition of the if is True will the code of that branch be included in the compiled binary. The if statement will never run during run time.

Even better, you could also use the if_defined[] technique to set the alias debug_mode to True only if the program was started with a command-line option debug_mode, like this:

$ mojo -D debug_mode parameter_if_cmd.mojo

Our alias is then defined with:

from sys import is_defined
alias debug_mode = True if is_defined[”debug_mode”]() else False

That way, you don’t have to change the program code, only a command-line option is needed to change the mode to debug. Start the program with:

$ mojo parameter_if_cmd.mojo

(or ./parameter_if_cmd) and the assertion code will not be included or executed.

We saw how to use @parameter in combination with if and for to run the code it precedes at comptime. We can also use this decorator to make a function run at comptime.

Running a function at comptime with @parameter

In the following example, the add function, which takes two integer parameters a and b and returns an integer, is executed at comptime because it is decorated with @parameter (see parameter_decorator.mojo):

fn add_print[a: Int, b: Int]():
    @parameter                        # A
    fn add[a: Int, b: Int]() -> Int:
        return a + b

    var x = add[a, b]()               # B
    print(x)

fn main():
    add_print[5, 10]()  # => 15
# A The add function is annotated with @parameter
# B The add function is called at comptime and its result is printed

This translates at compile time to:

fn add_print():
    var x = 15
    print(x)

fn main():
    add_print()

The add calculation ran at compile time, so you pay no run-time price for anything inside the function.

Closures in Mojo can also handle parameters. Let’s first show what a closure is, and then discuss how they work with parameters.

Closures

A function takes values in as arguments when it is called and processes these; this is how a function gets its data. But there is another way that a function can get data from the surrounding scope, used with nested functions. This is often called capturing data, and the function is called a closure: it copies in (closes over) the variables to get its data. The captured variables are owned by the closure. The variables that are captured must be initialized before the definition of the function itself. Capturing means that the closure knows the values of any variables in context.

Listing 4 is an example of a closure inner(), which captures the value of the num variable (see closure.mojo):

Listing 4 — A closure capturing variables

fn outer(f: fn () escaping -> Int):   # A
    print(f())                        # B

fn call_it():
    var num = 5                       # C

    fn inner() -> Int:                # D
        return num                    # E

    outer(inner)

fn main():
    call_it()  # => 5
# A The function type of inner is fn () escaping -> Int
# B The closure inner is called here
# C The variable num will be captured
# D The function inner is a closure that captures the context variable num
# E num is known inside inner

The value of num is copied to the inner function. This all happens at run time, and such a closure can be passed as an argument to other functions, like in our example. The inner closure is passed to the outer function. inner() is called a run-time closure, and such closures have as type: fn() escaping → Type. The escaping keyword indicates that this closure can “escape” the scope in which it was defined, meaning it can be returned from the function and used elsewhere.

An error message you can get when you call a function but forget the argument list (), is the following: error: cannot emit closure for method ‘funcname’, or: function pointer was formed but not called, did you forget ‘()’s? Without (), Mojo thinks you want to use the function as a closure. Simply add () to the back of funcname to solve this.

Compile-time closures do exist also, as we’ll discuss now. To declare them we need the decorator @parameter.

Defining parametric closures with @parameter

Closures are local functions that can capture variables from their context, as we saw in the previous section. Now what if you would like to pass the inner function to the outer function, not as an argument, but as a parameter?

Then this code:

var num = 5
fn inner() -> Int:
    return num

outer[inner]()

results in an

error: cannot use a dynamic value in call parameter

Why is this? The inner function is dynamic because it is still executed at run time and thus cannot be passed as a parameter. Decorating the inner function with @parameter makes it static, which means it is executed at comptime, so it can be passed as a parameter. Of course, we also need to change the function header of outer, adding [] and not forgetting the () in the definition as well as the call. The keyword escaping now also needs to change to capturing, which indicates that a function can access and use variables from its enclosing scope.

The complete example with inner used as a parameter goes as follows (see parametric_closure.mojo):

Listing 5 — Defining a parametric closure

fn outer[f: fn () capturing -> Int]():    # C
    print(f())

fn call_it():
    var num = 5

    @parameter                             # A
    fn inner() -> Int:
        return num

    outer[inner]()                         # B

fn main():
    call_it()  # => 5
# A Decorator @parameter is needed to pass inner as a parameter
# B Passing inner as a parameter. Don’t forget the ()
# C The parameter declaration needs to declare the function parameter as capturing

Compare this code with the previous listing. It is a good exercise to change the code step by step, going from the previous code to the parametric code.

Closures like inner() are called parametric closures or compile-time closures. They capture values defined before their declaration: inner() captures the value of num. Their function type is always of the form: fn() capturing → Type.

To make sure that the captured value(s) are copied into the closure (instead of passing a reference to the closure) precede @parameter with the decorator @__copy_capture, like this:

@__copy_capture(num)
@parameter

Parametric closures are the backbone of stdlib functions like vectorize and parallelize, which are heavily used in calculations.

Structs with parameters

Like functions, generic structs can be defined with parameters declared between []. Many structs from the stdlib take a type as parameter. This is processed at comptime to generate optimal code for that type. The SIMD vector type, which was discussed in a previous article, is defined with two parameters as: struct SIMD[type: DType, size: Int].

Here is an example:

var sd = SIMD[DType.int16, 4](1, 2, 3, 4)

You can also enhance your own structs with parameters, as done in the following listing (see planets_param.mojo):

Listing 6 — Using parameters in struct definition

@fieldwise_init
struct Planet[earth_like: Bool]:             # A
    var mass: Int
    var name: String

    fn describe_planet(self):
        if earth_like:                       # B
            print(”Attention: Earth-like planet ahead!”)
        print(”Name:”, self.name, “Mass:”, self.mass)

fn main():
    var mars = Planet[True](80, “Mars”)      # C
    mars.describe_planet()  # =>
    # Attention: Earth-like planet ahead!
    # Name: Mars Mass: 80
# A Definition of parameter earth_like
# B Parameters can be used in method’s code
# C A value is given to the parameter when the struct is made

A parameter earth_like, which must be known at comptime, is defined for the struct Planet. Now when defining a new instance of Planet, you must give the parameter a value accordingly. This value can then be used in code, as we did here in the method describe_planet.

A general struct header schematically looks like this: struct[parameters](arguments).

Another stdlib type that uses parameters is List, defined in the module collections. List is like a workhorse in Mojo, used for many common tasks.

Lists in Mojo are homogeneous, containing only one type of items. This type can be specified at comptime as a parameter like List[Float64]. That’s why such a type is generic: you can define it for all types, like a List can contain Int16 values, or Float64, or String, or struct Person instances. The Dict type for a dictionary also takes key and value types as parameters. List and Dict are statically typed in Mojo; that is, the types of their data must be known at comptime.

New metaprogramming techniques will surely be added in the coming Mojo versions.

© 2025 Ivo Balbaert. All rights reserved.

This article is Part 3 of our ongoing series on the Mojo programming language. Part 1 introduced Mojo’s origins, design goals, and its promise to unify Pythonic ergonomics with systems-level performance.

Part 2 covered Mojo’s SIMD-first model in practice.

Mojo is created with a distinct Python flavor to bring unification to AI development and deployment.

Most AI LLMs today use Python as their main language. This means that MAX, the AI engine framework from Modular written in Mojo, must be able to talk to and use Python. Indeed, MAX has a Python API to work with Python AI models, as well as a Mojo and C API.

This article covers:

• A comparison between Python and Mojo

• How the integration between Mojo and Python works

• Showing the advantages of Mojo calling out to Python

• Working with useful Python functions and PythonObjects

• Working with local Python modules

• Applying functionality from modules in the Python ecosystem

• Calling Mojo from Python!!!!

Python can still do many things Mojo isn’t yet able to do, such as working with classes or operating on big integers. In the 35+ years of its existence, people have built a gigantic infrastructure of thousands of modules—from numerical computation (NumPy, Matplotlib), data science (Pandas), and AI (PyTorch, TensorFlow) to graphics, gaming, and beyond. Although Mojo equivalents are being built right now, it will take time to make them as battle-tested and functionally complete as their Python counterparts. So, for the foreseeable future, Mojo and MAX will need to work smoothly with Python.

Mojo is a member of the Python family of languages. It’s no surprise, then, that as a developer, you’ll need basic Python skills. More important is learning to read the documentation of Python libraries to understand the API required to talk to Python—calling Python functions from Mojo. Using existing Python functionality will help you, as a Mojo developer, build a complete working project faster, enriching your portfolio or that of your company.

In this article, you’ll learn how to do just that. Afterwards, the Python parts can be slowly migrated to Mojo, further enhancing your project’s performance.

To follow along, first follow the instructions here to install pixi. Then use pixi to create a project called python_integration and cd into it. We’re going to let Mojo work together with Python, so we need a running Python environment inside the Mojo project. Add a recent Python version such as 3.12 to the project with the command:

$ pixi add “python==3.12”

and start a magic shell.

To add the necessary Python libraries, run:

$ pixi add numpy matplotlib

All code examples used in this chapter can be found in the code repo here.

The code in this article uses Python integration and calculations at compile time. We’ll discuss these topics more in depth in later articles. All code has been tested in Mojo’s latest stable version 25.6.

A Comparison between Python and Mojo

We’ll start by converting a Python program to its Mojo equivalent step by step. The following section compares the same algorithm implemented in both Python and Mojo, and we compare the performance of both.

Compiling and executing a simple Mojo program

As a start, let’s do a Hello World! for the whole planet in Python (see hello_world_uni.py):

print(”Hello World from Python!”)
print(”Bonjour tout le monde!”)
print(”Hallo Wereld!”)
print(”¡Hola, mundo!”)
print(”Καλημέρα κόσμε!”)
print(”你好”)
print(”こんにちは 世界!”)
print(”ສະ​ບາຍ​ດີ​ຊາວ​ໂລກ”)
print(”👋🌍❗”)

Run it with:

$ python3 hello_world_uni.py

Output:

Hello World from Python!
Bonjour tout le monde!
Hallo Wereld!
¡Hola, mundo!
Καλημέρα κόσμε!
你好
こんにちは 世界!
ສະ​ບາຍ​ດີ​ຊາວ​ໂລກ
👋🌍❗

Now write the Mojo equivalent (see hello_world_uni.mojo):

Listing 3.1 – A Unicode Hello World! program

def main():
    print(”Hello World from Mojo!”)
    print(”Bonjour tout le monde!”)
    print(”Hallo Wereld!”)
    print(”¡Hola, mundo!”)
    print(”Καλημέρα κόσμε!”)
    print(”你好”)
    print(”こんにちは 世界!”)
    print(”ສະ​ບາຍ​ດີ​ຊາວ​ໂລກ”)
    print(”👋🌍❗”)

For a change, let’s run it on the command line, outside of VS Code:

$ mojo hello_world_uni.mojo

(This is short for: mojo run hello_world_uni.mojo.)

As expected, this displays the same “Hello World” messages as Python.

We see that Mojo is as friendly as Python and supports Unicode. You’ll notice that in Mojo all statements are enclosed in a block preceded by def main():

In Python you can write top-level code, but in Mojo this is not yet possible (except in the REPL or in a Jupyter notebook): all code must be enclosed in a function.

Moreover, the top-level code must be written in a main() function with no arguments and no return type. main() is automatically called as the starting point of execution in Mojo. It also envelops the complete program execution from start to end.

Looking at the Mojo version, you’ll see quite a lot of Python features:

• def to declare a function

• The : character to end a function or control statement, marking the start of an indented code block

• Significant whitespace and indentation

print() is a function that displays its argument to the terminal, including a newline.

Experiment:

Experiment with removing or adding spaces before the print statements and see what the compiler thinks about this. “Statement has excess indentation” will remind you when the indentation is wrong. By convention, Mojo uses four spaces per indentation level. Each level starts a new code block. Make sure your code editor uses spaces only and converts tabs to spaces.

The mojo command compiles to machine code and executes that in memory—it doesn’t produce an executable file.

Building the code into an executable

A typical production environment doesn’t have MAX or Mojo installed. This isn’t necessary, because a Mojo project compiles to a single executable file with the mojo build command.

This simplifies deployment tremendously: you just copy the executable to the target production machine and run it. Let’s try this:

$ mojo build hello_world_uni.mojo

Now a binary file hello_world_uni is produced, which you can execute as ./hello_world_uni, displaying the same output as before.

Go ahead, do it. Copy it elsewhere on your machine and see that it runs.

Note: In development, the simple mojo command to run a program is just fine. You’ll need a build only when deploying into a test or production environment. It’s also important for benchmarking: an executable usually runs at higher speed because no JIT compilation is needed.

Converting Python programs to Mojo

In this section, we’ll see that there isn’t much difference between a simple Python program and its Mojo equivalent. Then we’ll look at a non-trivial Python program and convert it step by step to Mojo.

A simple example

Here is a Python program to add two integers (see adding.py):

def add(x, y):
    return x + y

z = add(3, 5)
print(z) # => 8

which we could rewrite as (see adding2.py):

def add(x, y):
    return x + y

def main():
    z = add(3, 5)
    print(z) # => 8

main()

Running both programs yields 8.

Now make a copy of this program and rename it to adding2.mojo. When compiling in VS Code, you’ll see the following error:

error: TODO: expressions are not yet supported at the file scope level

We get rid of this by removing the call to main(), which isn’t needed in Mojo. Then, in def add(x, y):, we see another error:

error: argument type must be specified

That’s right—even in a def function, the arguments and the return value must be typed. Because the values are integers, they have the type Int.

The resulting program is valid Mojo code:

def add(x: Int, y: Int) -> Int:
    return x + y

def main():
    z = add(3, 5)
    print(z) # => 8

Note that when running this code, Mojo does not use CPython or any Python interpreter. Mojo also has a more robust style using fn as the keyword for a function instead of def. In fn mode, it is mandatory to add a type to every function argument, and the function must be annotated with raises if an error can occur inside the function.

Why is argument typing important? First, with type info, the compiler can check whether the arguments passed to the function have the correct type. The wrong type will give a compile error, rather than crashing your program at runtime as Python can. The code becomes more robust; you don’t even have to run it to catch certain errors. Second, since the compiler knows the exact types, it can generate machine code specifically for those types. For example, code for integers will differ from code for floating-point numbers. Doing so, the machine code can be highly optimized, leading to a big performance increase.

Let’s make this change in the code (see adding.mojo):

fn add(x: Int, y: Int) -> Int:    #A
    return x + y

fn main():
    z = add(3, 5)
    print(z)  # => 8

#A Adding argument types for robustness and performance

def and fn

Now you might ask: what’s with def versus fn, and how do I choose which to use?

• def is as if you said to the compiler, “I just want to code—stop bothering me; speed is not my concern.” It’s more Pythonic. Mojo assumes any def function can raise an error. Functions are dynamic and types are optional for local variables. def is great for high-level programming and scripting but less suited to systems-level programming. Yes, you can use types with def when declaring variables with var, and this is mandatory for function arguments. But then, why not use an fn function?

• fn is as if you said to the compiler, “Let’s get fast—and show me everything that could go wrong.” It’s the Rust way: statically typed and aiming for higher performance. fn enforces strongly typed code and guarantees memory-safe behavior.

If the compiler thinks there is any chance of an error being raised inside the function, the function must be annotated explicitly with raises to indicate this.

Declaring the type with var is not required for variables inside an fn, but it’s considered best practice: with type info, the compiler can generate faster, safer code.

Both def and fn warn you when a variable is unused, to guard against misspellings or superfluous variables.

Experiment:
In the typed Mojo program adding.mojo, try to add two decimal numbers. Does it work? What message do you get? Do you get the message at compile time or when running the program?

An algorithmic example: binary search

Here we start with a non-trivial Python program and convert it step by step to Mojo (see search.py). What does this program do?

The code contains a binary search function that takes a sorted array arr and an element x. It searches whether x is present in this array, returning its index; otherwise it returns −1.

Note: The binary-search algorithm used here is widely known. If you need a refresher, see read this.

Listing 3.2 – A binary search Python program

def binary_search(arr, x):
    low = 0
    high = len(arr) - 1
  
    while low <= high:
        mid = (high + low) // 2

        if arr[mid] < x:
            low = mid + 1
        elif arr[mid] > x:
            high = mid - 1
        else:
            return mid

    return -1

# top-level code:
n = 1_000_000         #A
arr = []
for i in range(n):
    arr.append(i)     #B           
results = []                
for i in range(n):    #C          
    results.append(binary_search(arr, n - i))
print(”Results: “, len(results))

# => Results:  1000000

#A The _ can be used in numbers to make it easier to read 
#B First loop: populate array arr
#C Second loop: call binary search 1,000,000 times

The main code sets up the data structures. The first loop appends all numbers from 0 to 999,999 to the array. Then, in a second loop over the 1,000,000 numbers, it performs a binary search on each integer n – i, which must be present in the array. The // operator inside the function means floor division (for example, 5 // 2 gives 2). At the end, we display the length of the results array to verify we have found all numbers.

Let’s now convert this program to Mojo. First make a copy of search.py and rename it to search.mojo.

Immediately, the editor fills with (luckily all the same) errors:

TODO: expressions are not yet supported at the file scope level.

Tip: Put your cursor on the error line, then use F8 to enlarge the message or copy it.

We know how to handle this: just place a def main(): before the top-level code and indent the code.

The next error we see is:

cannot emit an empty list without a contextual type

for the arr and results variables. Like in Python, we want them to be dynamic lists.

The closest to this in Mojo is List, which is defined in the module collections but is automatically known.

Instead of declaring arr as an [], we must declare it with its List type: arr = List[Int32](), and do the same for results. They are both a List of 32-bit integers. The () at the end is a call to the List constructor. Basically, we have given the two variables a type, which makes the code more error-proof and speeds up the execution.

We still have an error on the def binary_search:

argument type must be specific

The arguments must be typed in both fn and def functions. Let’s fill in the concrete type: def binary_search(arr: List[Int32], x):.

While we’re at it, let’s type the search argument x as a 32-bit integer as well:
def binary_search(arr: List[Int32], x: Int32):.

Now we see another error on the return lines:

cannot implicitly convert ‘Int’ value to ‘None’ in return value

The result of binary_search, which is the position of x in the array arr, is not indicated. This cannot be converted to an Int32, which is the element type of results and exactly what append expects.

Let’s specify the return type with -> Int32:
def binary_search(arr: List[Int32], x: Int32) -> Int32:

(We get a warning on the line mid = 0; this line can be deleted because mid is initialized in the while loop.)

Finally, our Mojo code compiles and displays the same output as the Python code. Note that the code block of binary search is exactly the same in the Python and the Mojo version.

Since we clearly moved our code to a stricter version of Mojo with types, change def to fn for the two functions. The resulting code is shown below (see search.mojo).

Listing 3.3 – A binary search Mojo program

fn binary_search(arr: List[Int32], x: Int32) -> Int32:    #B
    low = 0
    high = len(arr) - 1

    while low <= high:
        mid = (high + low) // 2

        if arr[mid] < x:
            low = mid + 1
        elif arr[mid] > x:
            high = mid - 1
        else:
            return mid

    return -1

fn main():
    n = 1_000_000
    arr = List[Int32]()        #C
    for i in range(n):
        arr.append(i)
    results = List[Int32]()    #C

    for i in range(n):
        results.append(binary_search(arr, n - i))
    print(”Results: “, len(results))

# => Results:  1000000

#B Typed binary search function
#C Typing arr and results

With very little effort (changing three lines), we converted the Python code to Mojo. Let’s now see how they perform.

Comparing the speed of Python and Mojo in a simple algorithm

In the previous section, we used a binary-search algorithm and executed 1,000,000 calls to that function. We wrote both a Python and a Mojo version. Let’s now time the difference.

This is very simple:

• Capture the time before the loop that calls binary search (call it start) and after that loop (end). So (end - start) is the time difference.

• To work with time in Python, import it: from time import time.

• The time is returned in seconds; to get milliseconds (ms) multiply by 1000.

• To work with time in Mojo, use the perf_counter_ns() function and import it from the module time: from time import perf_counter_ns.

• The time there is returned in nanoseconds; to get ms divide by 1,000,000.

We are not making a real benchmark here; we just want an idea of the difference between the two versions.

Comparing Python and Mojo, we show the Python version in Listing 3.4 (see search_timed.py; we leave out code common with Listing 3.2):

Listing 3.4 – Timed Python binary search

from time import time

def binary_search(arr, x):
                            #A

# top-level code:
                            #A
start = time()
for i in range(n):
    results.append(binary_search(arr, n - i))
end = time()
print((end - start) * 1000, “ms”)

# => 1290.342092514038 ms

#A Same code as in Listing 3.2

An average of 10 runs gives 1269 ms on my machine.

In the Mojo version, the variables and the binary_search function are typed.

Listing 3.5 – Timed Mojo binary search

from time import perf_counter_ns     #A
from collections import List         #A

fn binary_search(arr: List[Int32], x: Int32) -> Int32:
                          #B
fn main():
                          #B
    start = perf_counter_ns()
    for i in range(n):
        results.append(binary_search(arr, n - i))
    end = perf_counter_ns()
    print((end - start) / 1e6, “ms”)

# => 56.476036999999998 ms

#A Import perf_counter-ns and List from their modules time and collections
#B Same code as in Listing 3.3

An average of 10 runs gives 57 ms, which is 22.3× faster than the Python version! The algorithm and loops remain the same, and the code still looks very Pythonic.

Why use Python together with Mojo?

Mojo is a young language and currently doesn’t have many battle-tested libraries outside of stdlib. Python, by contrast, is decades old and has a vast ecosystem of well-tested libraries. It’s evident that Mojo projects would want to use these modules. Also, the gigantic amount of Python code that exists as modules in applications must be reusable in new Mojo projects.

As time goes by, Mojo equivalents for these Python libraries will appear and replace them. In the meantime, use Python for what it’s good at—for example, graph plotting or AI modeling with PyTorch—and for things that do not yet exist or are more difficult to rewrite in Mojo.

Why can you be confident that the Mojo ecosystem will grow rapidly? Because Mojo, being compiled, delivers far better performance (in the range 10–10000, and when fine-tuned even more) than Python, which is interpreted. With what we now know about Mojo, we can answer the following question in more depth.

Why is Mojo more performant?

• With Mojo, there is no overhead associated with compiling to bytecode and running through an interpreter as Python does. Mojo compiles to native code, which runs inherently much faster.

• Python works with references (a kind of pointer) for all variables, even for simple numbers. Mojo, on the other hand, always uses SIMD for numbers and math operations. Numbers (and other simple values) sit on the stack and can be passed straight into SIMD registers to be processed in bulk. We don’t need to look up these values on the heap via an address as in Python.

• All the expensive allocations on the heap, garbage collection, and indirections (looking up values through references) that Python does are not required in Mojo.

• The Mojo compiler can do huge optimizations because it knows the types of its variables. For example, knowing which numeric type is used in a piece of Mojo code can lead to highly optimized executable code. Because Python doesn’t know the type of its variables, it can’t do AOT (ahead-of-time) optimizations.

Two-way communication

Python–Mojo two-way communication is needed to get Python developers on board and to gradually migrate Python projects to Mojo.

What currently works very well is Mojo calling out to Python and getting results back. The other way around—Python calling into (much more performant) Mojo code—is also possible, but a bit more involved at the moment.

Conversion tool from Python to Mojo

An automated Python-to-Mojo code translation tool would be very helpful and will be provided by Modular. An open-source attempt, py2mojo by Manuel Saelices, can be found here.

Mojo’s long-term goal is to become a superset of Python. Then it will no longer use CPython. No intermediary solution will be necessary because Mojo’s compiler will process all code as Mojo code, including when it is written as pure Python.

Mojo calls Python – A simple example

If you are a Python developer, you probably have many favorite Python libraries and a bunch of self-written Python code for your projects. You don’t want to throw that away—you want to use that code from Mojo. And of course, you want to use modules across the Python ecosystem as well. We’ll show you how to do just that, starting with a simple example and later using well-known Python libraries, all with the same simple technique.

Suppose we have our own Python module compute.py containing some functions for calculations. To keep it simple, let’s start with multiplication and exponentiation:

def mul(n, m):
    return n * m

def pow(n, m):
    return n ** m

Let’s add this functionality to our Mojo program by importing the Python module. Python inside Mojo is a different execution environment, so Mojo braces against possible errors occurring in Python by using the raises keyword (see main.mojo):

Listing 3.6 – Mojo using a local Python module

from python import Python       #A

fn main() raises:               #E
    var i: Int = 42
    var j: Int = 7

    Python.add_to_path(”.”)      #B
    var calc = Python.import_module(”compute”)    #C

    var res1 = calc.mul(i, j)    #D
    var res2 = calc.pow(i, j)
    print(res1, res2)  # => 294 230539333248

    var np = Python.import_module(”numpy”)        #C
    var arr = np.arange(7)		                #D	
    print(arr)  # => [0 1 2 3 4 5 6]

#A Import the python module. 
#B Adds a directory to the Python path.
#C Import the specific Python module to use.
#D Call the Python functions.
#E Calling Python from Mojo always needs raises.

The python module (part of Mojo’s stdlib) is all that is needed for Python integration. The add_to_path() function tells Python where it can find the Python module to be used. compute.py lives in the current directory, which we include with “.”. If the Python module is stored elsewhere in your filesystem, change this to Python.add_to_path(”/path/to/module”).

Experiment: Using a module from another folder
Now your compute.py is stored in a subfolder calculations, which is itself in a subfolder my_python under the location of main.mojo. Change add_to_path so that it works.

Python.import_module() does what it says (note that the .py extension is not needed). Just give it a name, then call the Python functions you need with the familiar dot notation, like calc.mul(i, j) or np.arange(7). Continue with their results in the Mojo code.

The Python struct imported and used in the code is only a collection of static methods (like add_to_path and import_module) that enable you to use Python code in Mojo. They are called static because they are called on the Python struct itself, like Python.import_module() (see Chapter 6).

Note
Code that uses Python in a Jupyter notebook must be preceded with %%python:

%%python
print(”The answer is”, 42)	# => 42

Let’s explore a little more in depth how this all works. CPython is the standard Python interpreter, and the same interpreter is used by Mojo to process Python code. This ensures that Python works exactly the same as it does when running stand-alone.

When processing Python code in Mojo, CPython is called at compile time and communicates with the Mojo compiler. This means that all Python processing happens at comptime. Mojo knows only one type for communication with Python, called PythonObject, which is used to contain all Python data.

Tip: A Mojo executable that uses Python does not contain the Python environment. So, you must ensure the production environment has Python installed—for example, as we did with:
$ pixi add “python==3.12”.

Also, every Python module used must be separately installed in that environment. Pixi makes this easy. If a required Python module is not present, the Mojo program will crash. For example, if NumPy is needed, install it with:
$ pixi add numpy.
To add modules not available through the conda repo, you can also access PyPI through a command like:
$ pixi add --pypi “fastapi”, which adds the fastapi library.

Note: When you work with Python in a Mojo project, a folder __pycache__ is created, which contains .pyc files created by CPython (in our example a file compute.cpython-312.pyc). The next time the Python code is called, the bytecode compilation can be skipped.

Python calls Mojo

As said, this can already be used, but because this is a beta feature many changes will take place before it reaches maturity. You can find out more here.

Using functions from the python module

The following listing shows how to use the crucial import_module function, as well as the complementary add_to_path function. But the Python struct contains other useful functions, like eval and evaluate (see python_functions.mojo):

Listing 3.7 – Useful python functions

from python import Python
from memory import UnsafePointer

fn main() raises:
    var py = Python()            #A

    var x = py.eval(”if 108 >= 42: print(’ok’)”)  # => ok
    print(x)  # => True

    var t = py.eval(”108 < 42”)    #B
    print(t)  # => True

    print(py.eval(”108 >< 42”))
    # =>
    #   File “<string>”, line 1
    # 108 >< 42
    #      ^
    # SyntaxError: invalid syntax
    # False

    var y = py.evaluate(”42 * 7”)   #C
    print(y)  # => 294
    var pystr = py.evaluate(”’This string is built’ + ‘ inside Python’”)
    print(pystr)  # => This string is built inside Python
    var len_py = Python.evaluate(”len”)   #D
    print(len_py(”ABCDEFG”))  # => 7

    var w: Int = 42
    var pybt = Python.import_module(”builtins”)  #E
    pybt.print(”This uses the Python print function”)
    # => This uses the Python print function
    pybt.print(”The answer is”, w)  #F
    # => The answer is 42
    pybt.print(pybt.type(w))  # => <class ‘int’>    #G
    pybt.print(pybt.id(w))  # => 139804414609064    #G
    print(UnsafePointer(to=w))  # => 0x7ffcda444ea0

    var foods = Python.list()    #H
    foods.append(”carrot”)
    foods.append(”chicken”)
    print(foods)  # => [’carrot’, ‘chicken’]
    print(Python.type(foods))  # => <class ‘list’>

#A Make a shorthand for Python()
#B Using eval to check and run Python code, returns a Bool
#C Using evaluate to execute Python code, and return result
#D Taking the Python len function into Mojo
#E Import Python builtins to use its functions
#F Python can use Mojo’s variables
#G Using Python’s print, type and id functions
#H Creating a Python list

Python() creates an object of the Python struct (see Chapter 7), so we can give it a shorter name (here py) and call the various functions on it.

The eval function accepts a (reference to a) String and executes it if the string is valid Python code, returning True (even if the expression evaluated is false). If the code is not valid or raises an exception, it returns False.

The evaluate function also executes the first String argument as Python code, but it returns the result of the evaluation as a PythonObject, to be used in Mojo. You can even use it to access a built-in Python function like len, store it in a Mojo variable, and call it in Mojo.

Another way to do the same thing is to import the Python builtins module, give it a name, and start calling functions from this module, as in pybt.type (which gives you the dynamic type) and pybt.print().

Python can also use a Mojo variable (in this example w). From the addresses (id in Python, address_of in Mojo) we can see that Python takes a copy of the variable. That copy is of type Int (or a PythonObject constructed from an Int) for Mojo, and <class ‘int’> for Python.

The list() and dict() functions construct an empty Python list and dict, and you use pure Python to work with them. For Mojo, these variables remain of type PythonObject.

Working with PythonObject

We already stated that all interaction between the Python interpreter and the Mojo compiler happens at comptime. A single, versatile type called PythonObject forms the bridge between Python and Mojo:

• All Python objects are viewed by Mojo as instances of PythonObject (an instance is a concrete version of a struct or class).

• A PythonObject can be constructed from a wide variety of Mojo types (SIMD types, String, StringRef, StringLiteral, Dict, and so on) and can be used with functions such as str, int, len, and so forth.

Moreover, PythonObject is register-passable, meaning the value can pass as a whole into SIMD registers, so it can be processed quickly. The import_module function also returns a PythonObject, which is a reference to the imported Python module. We give it a name (e.g., calc), and you can call all module functions on that object, like calc.mul(i, j). The types of the results of these calls are then inferred by the Mojo compiler and further processed in Mojo.

Nearly every operation involving a PythonObject may raise a Python exception, so functions that use it must be marked raises and handle errors.

PythonObject can be used in powerful ways, as the following examples demonstrate (see python_object.mojo):

• We can use all Python types in Mojo just by giving them an alias name, as §5.4.1 shows where we use Python exponentiation **, or §5.4.2 where we call the Python hex() method on its float type.

• Another way to use Python types is by using the Python.evaluate() function, as illustrated in §5.4.3. This can be used to construct a PythonObject from a literal expression, like Python.evaluate(”[42, ‘cat’, 3.14159]”), which acts like a Python list object.

This is useful when Python has functionality that Mojo doesn’t (yet) have. Rather than writing it in Mojo yourself, you can quickly use the Python version to accomplish your goal. For example, at the moment Mojo doesn’t support lists (or dictionaries) with different item types, so you could use a Python list that can contain heterogeneous types. In the following example we create a Python list object py_list and dynamically add items of different types:

from python import Python

def main():
    py_list = Python.list()     #A
    py_list.append(7)           #B
    py_list.append(”forty_two”)
    py_list.append(2.718)
    py_list.append(True)
    print(py_list)  # => [7, ‘forty_two’, 2.718, True]  #C
#A Create a Python List
#B Append different type elements

Tip Beware that PythonObjects are stored on the heap and must be garbage-collected; use them only when you can’t write pure Mojo code.

You can initialize a PythonObject in several ways:

from python import Python, PythonObject
alias py = PythonObject

var py: PythonObject = []    #A
var py = Python()  
var py: PythonObject = {}    #B    

#A Creates an empty Python list; you can append items and print the list as in the previous snippet
#B Creates an empty Python dictionary

Or we can extract Python types to use them in our Mojo code like this:

alias int = PythonObject
alias str = PythonObject
alias float = PythonObject

How to work with big integers in Mojo

Using Python’s int as PythonObject, we can benefit from arbitrary-precision integers:

    var x: int = 2 #A
    print(x**100)  # => 1267650600228229401496703205376
    var y: Int = 2 #B 
    print(y**100)  # => 0

#A x is a Python int, giving arbitrary precision in operations
#B y is a Mojo Int, with limited precision, and overflow without warning

Python gives us the right answer here, while Mojo Int does not because it overflows.

Note: The community package decimojo has a BigInt type, which works like int in Python.

Using PythonObject for floats and strings

In the following snippet, f and s1 are Python objects of type float and str, showing the use of Python functions hex and upper:

    var f: float = 0.6
    print(f.hex())  # => 0x1.3333333333333p-1
    var s1: str = “xxbaaa”
    print(s1.upper())  # => XXBAAA
    var s2: String = String(s1)
    print(s2)  # => xxbaaa

The Python str s1 is translated to Mojo String s2 by calling the Mojo String constructor on it.

Iterating over Python collections

The for loop supports iterating over Python collection types. Each item retrieved by the loop is a PythonObject wrapper around the Python object, so you don’t need to dereference it like in Mojo collection for loops. The following snippet is a simple example of iterating over a mixed-type Python list and dict:

    var py_list = Python.evaluate(”[42, ‘cat’, 3.14159]”)
    for py_obj in py_list:
        print(py_obj, end=” / “)
    # => 42 / cat / 3.14159 /
    print()
    var py_dict = Python.evaluate(”{’a’: 1, ‘b’: 2.71828, ‘c’: ‘sushi’}”)
    for py_key in py_dict:
        print(py_key, py_dict[py_key], end=” / “)
    # => a 1 / b 2.71828 / c sushi /

Working with Python modules

In this section we’ll show some useful Python modules at work within Mojo. Before calling into them, ensure your Mojo program can find them.

Test if a Python module is installed

An error may occur when attempting to import a module that isn’t installed locally. In Mojo, handle errors with try to run the dangerous code and except to catch the error.

Suppose we need the pandas module to work with data frames. Use the following code to avoid crashing your program when pandas (or any other Python module you want to use) is not available (see importing_error.mojo):

from python import Python

fn main():
    try:
        var pd = Python.import_module(”pandas”)
        print(pd.DataFrame([1,2,3,4,5]))        #A
    except ImportError:
        print(’error importing pandas module’)  #B

#A Prints   
    0
0  1
1  2
2  3
3  4
4  5 
when pandas is available       
#B Print ‘error importing pandas module’ when pandas is not available

To test this, execute it first with pandas not installed, and then make the library available with $ magic add pandas.

Making an HTTP request

We need the requests module, so install it with $ magic add requests. The following code using the Python requests module shows how easy it is to make an HTTP request (see http_request_from_py.mojo):

from python import Python

fn main() raises:
     var requests = Python.import_module(”requests”)
     var response = requests.get(”https://www.google.com/”)    #A
print(response.status_code)  # => 200
print(response.text)

# =>
<!doctype html><html itemscope=”“ itemtype=”http://schema.org/WebPage”   # lang=”pl”><head><meta content=”text/html; charset=UTF-8” http-           # equiv=”Content-Type”><meta …

response = requests.get(”https://api.github.com”)
print(response.json())    #B

# =>
‘current_user_url’: ‘https://api.github.com/user’, ‘current_user_authorizations_html_url’: 
‘https://github.com/settings/connections/applications{/client_id}’, ‘authorizations_url’: 
‘https://api.github.com/authorizations’,

#A The get function retrieves the raw HTMl from the website
#B Or if the content is JSON-formatted, get it in that format with the json() function

Note: If you want to work with a pure Mojo version, try out Lightbug_http, which is a simple and small HTTP server made by the community.

Using NumPy and Matplotlib

Many projects in scientific computing, data analysis, and machine learning use NumPy, an open-source Python library for efficiently manipulating large multi-dimensional matrices. A similar Mojo library is in the works, called NuMojo, which is complementary to the Mojo stdlib.

When starting to migrate a Python project to Mojo—or if you’re a NumPy expert intent on using this library—you can call NumPy from Mojo. Let’s see it at work (see numpy_graph.mojo):

Listing 3.8 – Using numpy and matplotlib

from python import Python, PythonObject

alias np = PythonObject     #A
alias plot = PythonObject

fn use_numpy(np: PythonObject) raises:
    var arr1 = np.array([1, 2, 3])     #D
    print(arr1)  # => [1  2  3]

    var arr2 = np.ndarray([5])         #D
    print(arr2)
    # => [4.67092872e-310 0.00000000e+000 0.00000000e+000 4.67150278e-310 2.37151510e-322]
    arr2 = “this will work fine”       #E 
    print(arr2)  # => this will work fine

    var arr3 = np.arange(15).reshape(3, 5)     #D
    print(arr3)
    # =>
    # [[ 0  1  2  3  4]
    # [ 5  6  7  8  9]
    # [10 11 12 13 14]]
    print(arr3.shape)  # => (3, 5)

fn use_matplotlib(np: PythonObject, plt: PythonObject) raises:
    var arr1 = np.array([1, 2, 3, 4])
    var arr2 = np.array([30, 20, 50, 60])
    plt.plot(arr1, arr2)    #F
    plt.show()              #F

fn main() raises:
    try:
        np = Python.import_module(”numpy”)    #B
        plot = Python.import_module(”matplotlib.pyplot”)
        use_numpy(np)
        use_matplotlib(np, plot)
    except ImportError:		            #C
        print(”Module numpy or matplotlib is not installed”)  

#A Make references to the Python modules as aliases.
#B Import the two modules inside a try/except.
#C Show an error when a module cannot be found.
#D Use the numpy array, ndarray and reshape methods.
#E Python is loosely typed.

We applied the technique from the previous section to test for an error when importing the modules. In use_numpy, we showed the array and ndarray methods (used when more efficient processing is needed), and how to make matrices with reshape.

arr2 is clearly a Python variable: it can change its type from array to string, which is impossible for a pure Mojo variable.

Then we call use_matplotlib. There we make two arrays that form the X- and Y-axes of a graph, which is shown here:

Figure 3.1 – Plotting a graph with matplotlib

Here is another example using the same pattern. After importing the necessary modules, it calculates a cosine graph and displays it with Matplotlib (see py_mojo_simd.mojo):

Listing 3.9 – Using numpy, matplotlib and SIMD

from python import Python, PythonObject
from math import math                            #H

alias np = PythonObject
alias plot = PythonObject
alias size = 256
alias element_type = DType.float64

fn use_python(np: PythonObject, plt: PythonObject) raises:
    var py_result = np.linspace(0, 255, 256)      #A
    # print(py_result)
    # =>
    # [  0.   1.   2.   3.   4.   5.   ...   253. 254. 255.]
    var simd_array = SIMD[element_type, size]()   #B
    for i in range(size):                         #C
        simd_array[i] = Float64(py_result[i])
    simd_array = math.cos(simd_array * (math.pi * 2.0 / 256.0))    #D
    # print(simd_array)
    # =>
    # [1.0, 0.9996988186962042, 0.9987954562051724, ...

    var graph = Python.list()         #E
    for i in range(size):             #F
        graph.append(simd_array[i])
    plt.plot(graph)  	           #G
    plt.show()  		

fn main() raises:
    try:
        np = Python.import_module(”numpy”)  
        plot = Python.import_module(”matplotlib.pyplot”)
        use_python(np, plot)
    except ImportError:
        print(”Module numpy or matplotlib is not installed”)  

#H This imports everything from the math module
#A Use linspace from numpy to get an evenly spaced array of 256 values from 0. to 255.
#B Create a Mojo SIMD vector with size 256.
#C Copy the Python array to the Mojo SIMD vector.
#D Calculate the cosine values using SIMD and Mojo math functions.
#E Make an empty Python list object.
#F Copy the SIMD vector into the Python list.
#G Display the graph using matplotlib from Python.

The curve is displayed in the following Figure 4.2:

Figure 4.2 – A cosine curve, calculated using numpy and SIMD and displayed with matplotlib

Note that because Python always returns PythonObjects, we must use a float conversion float(py_result[i]) when copying the Python NumPy vector to the Mojo SIMD vector of size 256. The calculation is done on this SIMD vector, which is faster than doing it in NumPy.

You don’t believe me? Then try it yourself!

Experiment: Comparing a NumPy calculation and its SIMD equivalent
Take the code from Listing 3.4 and add a Python calculation that does the same calculation on py_result as we did on simd_array. For this you’ll have to import the Python module math. The calculation itself must be done in a for loop.

Then time this calculation with the time module from Python, as we did in Chapter 3 §3.1.2.

Then also do the same for the Mojo SIMD calculation.

Results (on my machine): Python takes 2.48 ms, while Mojo takes 0.00328 ms, which is 756× faster!

Summary

• Python code is processed at comptime by the CPython interpreter.

• Python modules—local as well as from the ecosystem—can be used in Mojo through the import_module function.

• PythonObject forms the bridge between Mojo and Python. Through it, all Python types like int, str, List, and so on can be brought into Mojo code.

• While pure calculations are better executed in Mojo using SIMD and other features, Python modules like NumPy, Matplotlib, Pandas, and many others provide easy and quick access to specific functionality that may not yet exist in Mojo.

In the next part of the series, we will cover Compile-time metaprogramming in Mojo.

© 2025 Ivo Balbaert. All rights reserved.

This article is Part 2 of our ongoing series on the Mojo programming language. Part 1 introduced Mojo’s origins, design goals, and its promise to unify Pythonic ergonomics with systems-level performance.

Mojo is a high‑performance language. One of the main features enabling that goal is support for parallel processing at several levels:

• CPU calculations use SIMD automatically. A vectorize algorithm is available to support this data‑parallel processing at a higher level.

• Its runtime enables task‑parallel processing through automatic multithreaded code execution across multiple cores using the parallelize algorithm. This ensures maximum usage of all CPU cores.

• It supports execution on GPUs (which is intrinsically data‑parallel processing) with the same syntax used for CPU execution.

In this article we show the first way of parallelizing calculations in Mojo. Execution on GPUs will be addressed in a separate article.

We will first go deeper into what SIMD is and then demonstrate how Mojo works with it. We’ll talk about the following topics:

• What is SIMD?

• Mojo is SIMD first

• Retrieving and using SIMD system properties

• What is a SIMD vector?

• Working with SIMD vectors

• The @register_passable decorator

• Retrieving info about the host environment

• Harnessing SIMD with vectorization

The code in this article uses Python integration and calculations at compile time. We’ll discuss these topics more in depth in later articles. All code has been tested in Mojo’s latest stable version 25.4.

To follow along, first follow the instructions on https://docs.modular.com/max/get-started to install pixi. Then use pixi to create a project called simd and cd into it. We are going to let Mojo work together with Python, so we need a running Python environment inside the Mojo project. Add a recent Python version such as 3.12 to the project with the command:

$ pixi add "python==3.12"

and start a pixi shell. To add the necessary Python library, run:

$ pixi add matplotlib

What is SIMD?

SIMD is short for “Single Instruction, Multiple Data.”

This tells us that SIMD is a way to process data simultaneously (in parallel). It takes advantage of special hardware registers called SIMD or vector registers in the CPU processors of the machine. Modern CPU cores, including those in desktops, servers, and even mobile devices, contain such registers that can perform calculations simultaneously on fixed‑length vector data. This makes it possible for a single core to do up to 4, 8, 16, 32, or even 64 operations in parallel.

Their instruction sets have SIMD capabilities built in: Intel processors have SSE (Streaming SIMD Extensions) and AVX (Advanced Vector Extensions), and ARM Cortex‑A and Cortex‑R processors have the NEON SIMD instruction set.

For example, an Intel CPU with AVX‑512 has a 512‑bit vector register. This amounts to having 512/64 = 8 Float64 data items on which we can perform calculations simultaneously. The theoretical speedup is 8×, but in practice it will be lower due to memory read/write latency. The following schematic clarifies this:

Figure 1: A schematic of how SIMD works

Mojo has SIMD built in through the way its type system is set up. When you work with numerical types in Mojo, every operation is performed within SIMD registers.

Making an algorithm use SIMD fully is also called vectorizing. This is ideal for processing large amounts of data simultaneously, such as in image processing, artificial intelligence, and scientific calculations.

Mojo is SIMD first

Several languages (like C++, Rust, and so on) handle SIMD by using special libraries. But Mojo is unique in that SIMD is baked into the language: all numerical types and all built‑in mathematical functions on these types use it automatically. Python works with references (a kind of pointers) for all variables, even for simple numbers. In Mojo, numbers (and other simple values) sit on the stack and can be passed straight into SIMD registers to be processed in bulk. We don’t need to look up these values on the heap via an address as in Python.

All the numerical data types that can be used in a SIMD vector in Mojo fall under the DType umbrella. DType is a built‑in standard type defined as:

@register_passable(trivial)
struct DType

It contains the Bool type; 8‑, 16‑, 32‑, 64‑, 128‑, and 256‑bit signed and unsigned integer types (like UInt32 and Int256); and 8‑, 16‑, 32‑, and 64‑bit floating types (like BFloat16 and Float32).

For example, DType.float64 means the same as type Float64, and DType.uint32 means the same as type UInt32. Note that DType.float64 is a value, while Float64 is the real type.

Scalar[DType.float64] is another alias for the type of a single Float64 value.

The @register_passable decorator indicates that all of these types are handled through the SIMD registers.

SIMD should not be confused with parallel processing with threads executing on multiple cores. Each core has dedicated SIMD vector units, and we can take advantage of both SIMD and parallel processing to achieve massive speedup.

Retrieving and using SIMD system properties

To make the best use of the vector registers, it is important to know the SIMD capabilities of our target machine. The module sys.info contains a few functions to get that information (the results shown are for an Intel CPU with an AVX‑512 register):

from sys.info import simdbitwidth, simdbytewidth, simdwidthof

fn main():
    print(simdbitwidth())   # => 512
    print(simdbytewidth())  # => 64
    print(simdwidthof[DType.uint64]())   # => 8
    print(simdwidthof[DType.float32]())  # => 16

The function simdbitwidth shows the total number of bits that can be processed at the same time on the host system’s SIMD register. The result 512 means that we can pack 64 × 8 (= 512) bits, or 16 4‑byte numbers, or 8 8‑byte numbers together and perform a calculation on all of these with a single instruction.

The total number of bytes that can be processed at the same time is given by simdbytewidth (64 bytes on this machine).

Lastly, the function simdwidthof shows how many values of a certain type can fit into the target’s SIMD register. For example, use it to see how many UInt64s can be processed with a single instruction. On our system, the SIMD register can process 8 UInt64 or 8 Float64 or 16 Float32 values at once.

What is a SIMD vector?

SIMD is a way to process data in parallel: all items in a SIMD vector (which is basically a list of numbers) undergo the same instruction simultaneously. Simply put, instead of one instruction processing one number, one instruction processes 4, 8, 16, 32, or more numbers at a time. SIMD is used in every calculation in Mojo, so understanding it in depth is very important.

Vectors are a basic type in any systems language. Their typical syntax is like [1, 2, 3, 4], a numerical vector containing 4 elements. They are extensively used in calculations, which is why they are a first‑class type.

In Mojo, vectors are SIMD‑based and stored in stack memory, and they have a fixed size. A SIMD vector is defined as a struct with two parameters, type and size: struct SIMD[type: DType, size: Int].

Mojo allows the definition of generic structs which have parameters declared between []. Many structs from the stdlib take a type as a parameter. These parameters are processed at compile time to generate optimal code for that type.

Here is an example of a SIMD vector:

var sd = SIMD[DType.uint8, 4](1, 2, 3, 4)

Another way to define the same vector is:

var sd2: SIMD[DType.uint8, 4] = [1, 2, 3, 4]

The type of the vector’s elements is DType.uint8 or UInt8. The size or length of the vector is 4, the number of elements. Because of the hardware registers needed for SIMD, the size of a SIMD vector must be a power of 2, so 1, 2, 4, 8, and so on are all valid sizes. Vector registers are the fastest kind of memory access at the hardware level, but their number is limited, in many CPUs currently at 32. For a machine with simdbitwidth 512, the limit is 64.

To process the maximum number of values of a certain type (here Float32) simultaneously, you would use an expression like the following:

SIMD[DType.float32, simdwidthof[DType.float32]()]

This defines a SIMD vector that processes 16 Float32 values on a machine with a simdbitwidth of 512.

To explain how SIMD works, let’s compare the same operation (let’s say multiplying each element by 10) for a List with four elements 1, 2, 3, and 4, defined in Mojo as:

var lst = List[UInt8](1, 2, 3, 4)

and the SIMD vector sd from above with the same elements.

Using an ordinary List, we could use a for loop to do the multiplication, iterating over each item. Using a SIMD vector does the same work in only one operation, for all items at the same time. The following illustrates that principle:

Figure 2: SIMD processing: A SIMD vector is processed in one stroke, whereas a List has to be processed item by item.

A single instruction is processed across all its items at the same time (in parallel), instead of 4 separate instructions as when we use a for loop for the list. As an analogy: visualize the array of numbers as a bus with seats. Applying SIMD, with only one instruction, we can process the entire bus in the same amount of time it would have taken to process a single number in a non‑SIMD way.

Obviously, this is faster than processing these items one by one from start to end of the list: the same calculation done with a SIMD vector is 750× faster than a corresponding NumPy array calculation.

The following code shows the difference in processing all elements for a List compared to all elements of a SIMD vector:

Processing all elements in a List and in a SIMD vector

var lst = List[UInt8](1, 2, 3, 4)  # Defining a List with 4 elements
print("[", end="")  # This print stays on the same line

# All elements of the List are processed one by one, in sequence, in a for-loop.
for ref i in lst:                  # i is a reference
    i *= 10
    print(i, end=", ")
print("]")
# => [10, 20, 30, 40, ]

var sd = SIMD[DType.uint8, 4](1, 2, 3, 4)    # Defining a SIMD vector with 4 elements
# Another way to define the same vector:
var sd2: SIMD[DType.uint8, 4] = [1, 2, 3, 4]
print(sd2)  # => [1, 2, 3, 4]

# All elements of the SIMD vector are processed simultaneously, in parallel
sd *= 10
print(sd)  # => [10, 20, 30, 40]

To multiply every element in the List lst by a factor of 10, we have to go over the list with a for loop. The index i in the for loop is a reference and is made mutable by ref; it contains the address of the corresponding List element. Nothing of the sort is needed for the SIMD vector: we can simply use its name in every operation we want to apply on it, and the processing happens over all elements at once without going through a loop.

Working with SIMD vectors

Here are some basic operations with a SIMD vector:

print(sd)  # => [1, 2, 3, 4]
print(len(sd))  # => 4
assert_equal(sd[2], 3)
sd[2] = 5
print(sd)  # => [1, 2, 5, 4]

All operators like *, /, %, ** can be applied to SIMD vectors of the same size and type; for example, multiplying two SIMD vectors of size 4 is done in one operation. Math operations on SIMD values are applied elementwise, on each individual element in the vector, but simultaneously. You can cast SIMD values to the Bool type with Bool() and then apply &, |, ^, or other boolean operators.

If you leave the () empty in the definition of a SIMD vector, you make a vector of zeros. If you fill in only one value, it is taken as the default for all elements:

var zeros = SIMD[DType.uint8, 4]()
print(zeros)  # => [0, 0, 0, 0]

var ones = SIMD[DType.uint8, 4](1)
print(ones)   # => [1, 1, 1, 1]

The math.iota function is used to fill up a SIMD vector with subsequent integers:

var numbers = SIMD[DType.uint8, 8]()
print(numbers)  # => [0, 0, 0, 0, 0, 0, 0, 0]
# Fill them with numbers from 0 to 7
numbers = math.iota[DType.uint8, 8](0)
print(numbers)  # => [0, 1, 2, 3, 4, 5, 6, 7]

numbers *= numbers
print(numbers)  # => [0, 1, 4, 9, 16, 25, 36, 49]

all is a neat function to test a condition, which can be applied to all elements at the same time:

x = SIMD[DType.uint8, 4](2, 4, 6, 8)
if all(x < 3):
    print("all elements less than 3")
else:
    print("at least one element >= 3")
# => at least one element >= 3

Some other commonly used methods are join, interleave, and shuffle:

alias dtype = DType.float32

fn main():
    var a = SIMD[dtype, 4](0.5)
    var b = SIMD[dtype, 4](2.5)

    print(a.join(b))
    # => [0.5, 0.5, 0.5, 0.5, 2.5, 2.5, 2.5, 2.5]

    print(a.interleave(b))
    # => [0.5, 2.5, 0.5, 2.5, 0.5, 2.5, 0.5, 2.5]

    var c = SIMD[DType.int8, 4](42, 108, 7, 13)
    print(c.shuffle[1, 3, 2, 0]())  # => [108, 13, 7, 42]

The join function concatenates two SIMD vectors, and interleave weaves their elements together. shuffle rearranges the elements according to the mask indices given inside the [].

The Scalar type we talked about before, defining one number, is in fact a SIMD vector of size 1:

alias Scalar = SIMD[size=1]

This is shown here:

s1 = Scalar[DType.int32](42)
s2 = SIMD[DType.int32, 1](42)
assert_equal(s1, s2)

If we combine this with what we know from the Scalar type, we can state that Int32, Scalar[DType.int32], and SIMD[DType.int32, 1] all mean the same thing. This shows again that all numerical types are intrinsically SIMD defined.

A Mojo idiom is to use the SIMD type and size as compile‑time constants. We can define the type to be used (element_type) and the number of values (group_size) as aliases, as in the following listing:

Using the SIMD type and size as compile‑time constants

from sys.info import simdwidthof
import math

# Defining type and size as aliases
alias element_type = DType.int32
alias group_size = simdwidthof[element_type]()

fn main():
    # Initialize SIMD vector numbers with aliases
    var numbers: SIMD[element_type, group_size]
    numbers = math.iota[element_type, group_size](0)
    print(numbers)  # => [0, 1, 2, 3, 4, 5, 6, 7]

Working in this way, the vectors you define fit maximally in the SIMD register, which benefits performance.

The stdlib module complex also defines a type ComplexSIMD and methods to work with complex numbers having SIMD backing.

The @register_passable decorator

Any Mojo type whose value is of type AnyTrivialRegType is register‑passable. This means that its values can be used in SIMD registers, so we know such a type can be handled faster. These are also called trivial types, like Int, Bool, and any SIMD type. By default, they are stored on the stack.

We also have a way to indicate whether a value other than DType values—for example, the fields of a struct—can be processed in SIMD registers. This is done by annotating the struct with a register_passable decorator:

@register_passable
struct Coord:
    # all fields can be passed into SIMD registers
    var x: UInt32
    var y: UInt32
    var z: UInt32

When all the individual fields of a struct can be processed in SIMD registers, the struct as a whole can be passed into registers.

The generated code for the struct will then be optimized to work more efficiently.

Because the struct in our example has only fields of trivial types, we can make this clear by using: @register_passable("trivial").

If used in combination with @fieldwise_init (which generates a constructor called __init__ for all fields), the order of the decorators is important:

@fieldwise_init
@register_passable
struct Coord:
    # …

Retrieving info about the host environment

The more you know about the host machine your program will run on, the better you can tailor your code to gain speed or save memory. For example, you may want to know the type of your CPU and which specific features it has, which OS you’re running, and so on.

Based on this info, we could execute different code when we are on macOS compared to when we are running on Linux. Mojo has this info ready for you, stored as Bool values in sys.info, as you can see in the following code (results are for a machine that runs WSL2 in Windows 11):

from sys.info import (
    os_is_linux, os_is_macos, os_is_windows,
    has_avx, has_avx2, has_avx512f, has_intel_amx,
    has_neon, has_vnni, is_apple_m1, is_apple_m2, is_apple_m3,
    _current_arch, _triple_attr,
    num_logical_cores, num_physical_cores,
    has_nvidia_gpu_accelerator,
    has_sse4
)

from sys import CompilationTarget

fn main():
    var os: String
    if os_is_linux():
        os = "linux"
    elif os_is_macos():
        os = "macOS"
    else:
        os = "windows"

    var cpu = String(_current_arch())
    var arch = String(_triple_attr())

    print("The host OS is  : ", os)
    print("Its CPU is      : ", cpu)
    print("Its Architecture: ", arch)
    print("Number of Physical Cores: ", num_physical_cores())
    print("Number of Logical Cores: ", num_logical_cores())
    # =>
    # The host OS is  :  linux
    # Its CPU is      :  alderlake
    # Its Architecture:  x86_64-unknown-linux-gnu
    # Number of Physical Cores:  12
    # Number of Logical Cores:   24

    print("CPU-features:")
    if has_sse4(): print("sse4", end=" / ")
    if has_avx():  print("avx", end=" / ")
    if has_avx2(): print("avx2", end=" / ")
    if has_avx512f(): print("avx512f", end=" / ")
    if has_intel_amx(): print("intel_amx", end=" / ")
    if has_neon(): print("neon", end=" / ")
    if is_apple_m1(): print("apple_m1")
    if has_vnni(): print("avx512_vnni", end=" / ")
    if has_nvidia_gpu_accelerator(): print("NVIDIA-GPU")

    # =>
    # CPU-features:
    # sse4 / avx / avx2 / avx512_vnni / NVIDIA-GPU

A number of functions starting with has_ or is_ give info about the processor type and capabilities of the host system, among them are:

• has_sse4(): SSE4 is the older SIMD instruction extension for x86 processors (introduced in 2006).

• has_avx(): AVX (Advanced Vector Extensions) are instructions for x86 SIMD support. They are commonly used in Intel and AMD chips (from 2011 onwards).

• has_avx2(): AVX2 (Advanced Vector Extensions 2) are instructions for x86 SIMD support, expanding integer commands to 256 bits (from 2013 onwards).

• has_avx512f(): AVX‑512 (Advanced Vector Extensions 512) added 512‑bit support for x86 SIMD instructions (from 2016 onwards).

• has_intel_amx(): AMX is an extension to x86 with instructions for special units designed for ML workloads such as TMUL, which is a matrix multiply on BF16 (from 2023 onwards).

• has_neon(): Neon (also known as Advanced SIMD) is an ARM extension for specialized instructions.

• has_vnni(): the host system has avx512_vnni.

• is_apple_m1(): The Apple M1 chip contains an ARM CPU that supports Neon 128‑bit instructions and is GPU‑accessible through the Metal API.

Newer functions are regularly added; see https://docs.modular.com/mojo/stdlib/sys/info/.

Harnessing SIMD with vectorization

At the start of the article, we defined vectorizing as making an algorithm use SIMD fully. Fortunately for us, we don’t need to worry about the “making” part: Modular (the company that creates Mojo) provides a built‑in vectorize function in the algorithm package.

In the following example we calculate 256 values of the cosine function and then plot the graph using Python matplotlib. The calculations are done in a SIMD array tmp. For storage we use an UnsafePointer called array with its load and store methods. The names defined with alias become compile‑time constants. @parameter is a decorator for the cosine closure function, which ensures that the function runs at compile time and allows cosine to capture the array pointer.

The following code is executed on a machine where simdbitwidth() is 256, so simd_with gives 4, meaning 4 Float64 values fit into the SIMD register at a time:

Vectorizing the calculation of a cosine

from math import cos, iota, pi                 # Importing the necessary functions
from memory import UnsafePointer
from algorithm import vectorize
from python import Python, PythonObject
from sys.info import simdwidthof

alias size = 256
alias element_type = DType.float64
alias simd_with = simdwidthof[element_type]()

fn main() raises:
    # 1- Calculate the cosine array using vectorization:
    # Allocate array of size elements of type element_type
    var array = UnsafePointer[element_type].alloc(size)

    @parameter   # @parameter runs the function cosine at compile time
    fn cosine[simd_width: Int](n: Int):
        # Create a simd vector tmp of size simd_width
        var tmp = iota[element_type, simd_width](n)
        # print(tmp)
        # => [0.0, 1.0, 2.0, 3.0], [4.0, 5.0, 6.0, 7.0], until [252.0, 253.0, 254.0, 255.0]
        tmp *= pi * 2 / 256.0     # Convert radians to degrees
        tmp = cos(tmp)            # Calculate cosine
        # print(tmp, end="- \n")
        # => [1.0, 0.9996991239756597, 0.9987966769554031, 0.9972932019885731],
        # [0.9951896037943114, 0.992487148217141, 0.9891874614652418, 0.9852925291318769]
        # until [0.9948724987092192, 0.9970539358757885, 0.9986353937937995, 0.9996159208177102]
        array.store(n, tmp)       # Store the 4 calculated values in the UnsafePointer

    vectorize[cosine, simd_width](size)   # Vectorize the calculation

    # 2- Plot the cosine array using Python
    try:
        var plt = Python.import_module("matplotlib.pyplot")
        var graph = Python.list()
        for i in range(size):
            graph.append(array.load(i))
        plt.plot(graph)
        plt.show()
    except:
        print("error in plotting")

vectorize is called as:

vectorize[cosine, simd_width](size)

which here is:

vectorize[cosine, 4](256)

vectorize creates a loop calling cosine 64 times, 4 values at a time.

The cosine function is defined as:

fn cosine[simd_width: Int](n: Int)

and will be called with these values:

cosine[4](256)

Apart from the normal arguments enclosed within round brackets (), both of these functions also have data enclosed within square brackets []. These are called parameters. If needed, these are calculated at compile time and then stored as constants to use during runtime execution.

The net effect of vectorizing is that, on a machine with a SIMD register size of 256, this will set 4 Float64 values on each iteration, as we can see when we display tmp. This optimizes the effectiveness of the SIMD operations. The tmp values go from n to (n + simd_width – 1), where n varies from 0 to 64.

This is the resulting plot:

Figure 3: (Plot showing the cosine function)

The example from the previous section shows that vectorization simplifies SIMD‑optimized loops. Here is the definition of vectorize from the stdlib:

vectorize[origins: origin.set, //, func: fn[Int](Int) capturing -> None, simd_width: Int, /, *, unroll_factor: Int = 1](size: Int)

Notice that vectorize is a higher‑order function, which contains as a parameter a function with signature func: fn[Int](Int) capturing -> None. It has one Int parameter and an Int argument. Our cosine function conforms to that signature, with simd_with as parameter and n as argument.

Vectorization works by mapping a function across a range from 0 to size, incrementing by simd_width at each step. The remainder of size % simd_width, if not 0, will then run in separate iterations.

Up next:

© 2025 Ivo Balbaert. All rights reserved.

• Modular, MAX, and Mojo

• The problem Mojo addresses in the software industry

• The superpowers of Mojo

• Mojo’s tooling and ecosystem

• Where Mojo stands today

Modular, MAX, and Mojo

Modular is a software company founded by Chris Lattner (of LLVM and Swift fame) and Tim Davies. Its mission is to build a next generation AI developer platform called MAX (short for: Modular Accelerated Xecution), aimed at streamlining and simplifying AI development and deployment. MAX functions more like a framework, built upon the Mojo and Python. In fact, MAX’s core is written entirely in Mojo. The full platform is called the Modular software.

Modular’s business model involves deploying its software in enterprise environments and offering consulting services based on its deep technical expertise. However, The “Mojo Community Edition” which includes the Mojo language and the Max framework will always be open and free to use from their GitHub repo.

Mojo is a new Pythonic system-level language. It adopts most, if not all, of the conventions and keywords used in Python, making it accessible to Python developers. At the same time, it allows lower-level programming using pointers, buffers, and tensors when performance is critical. Modular has committed to open-sourcing the entire stack: the standard library is already open, and the Mojo compiler is expected to be open-sourced in 2026.

Mojo’s development is spearheaded by Chris Lattner and his team at Modular, and the language was first made public in May 2023. The language is designed to deliver speed and adaptability to emerging hardware platforms, all within the Pythonic syntax familiar to AI and ML developers. It does this in two ways:

• Although software performance is notoriously difficult to benchmark, Mojo regularly matches and sometimes surpasses the speed of Rust and C++, as we’ll see in later sections.

• Mojo is the first programming language that allows developers to target a wide range of hardware—including NVIDIA and AMD GPUs—without switching to CUDA. Unlike CUDA, which only works with NVIDIA GPUs, Mojo provides a unified programming model across platforms.

The problem Mojo addresses in the software industry

Python is an excellent language when it comes to the design and prototype stage of machine learning and AI projects, offering a comfortable syntax and a wealth of supporting tools and libraries. Unfortunately, it’s much less suitable when moving these projects to a production stage, where you need high performance to satisfy customers and reduce costs. For such tasks, you needed, until now, to switch to a different language like C++ or Rust, which offer good low-level performance.

The Mojo language changes this fragmented workflow entirely: with its Pythonic syntax, memory-safety and C++ like performance, Mojo is well suited for both the development and deployment stage of AI or any other projects for that matter.

Python is the number one language used in machine learning and AI projects. Not only that, it is also rated as the most popular language in the Tiobe index and other language popularity rankings.

Python makes prototyping and modelling easy. Its almost pseudocode-like readability, mild learning curve and vast ecosystem account for its immense popularity.

But Python also has its downsides: most importantly, it runs slow and doesn't know how to run code in parallel, wasting all the core-power of current CPU's and GPU's. Many attempts have been made to remedy these problems, none of them fully satisfactory.

Performance in an AI project is crucial. When reaching the deployment stage, engineers often rewrite parts of or the whole Python-project in a low-level systems language, preferably C++. Adding to that difficulty, to get access to GPU's, parts of the model must be rewritten in CUDA, or special accelerator languages for more exotic processors. So, two or three languages are needed, and the project's infrastructure becomes increasingly complex.

There is an urgent need for simplification in this domain. Model development and deployment both must be possible in one high-performant language. Not only that, the language should also be able to work directly with GPU's and other processors.

To remedy this situation, the industry needs a language that is both high-level like Python and low-level like C++ or Rust. This seems impossible, but Chris Lattner and his team at Modular are working on exactly such a language called Mojo. Chris Lattner is most known for the creation of LLVM (Low Level Virtual Machine) and more recently Multi-Level Intermediate Representation (MLIR), alongside Swift, Clang and work on TensorFlow.

LLVM and MLIR are both compiler tool chains: as input they get program code, and as output they generate executable machine code for any processor instruction set. Between input and output, any number of transformation steps can be defined to optimize the final binary code for the target machine. LLVM has revolutionized the programming languages world since 2003, most notably with Julia, Kotlin, Rust and Swift. MLIR is a sub-project of LLVM and aims at making machine code even more adaptable to specific hardware. Both MLIR and LLVM are used in Mojo. Because of this foundation, Mojo is the first programming language that can run on both CPU’s and GPU’s.

An example of Mojo code

Let’s now look at some Mojo code to get a sense of its syntax. The main() function is the typical entry point in a standalone Mojo program.

fn main():
    words = List[String]("Mojo", "is", "fire")    #1
    for ref word in words:                        #2
        word += "🔥"                              #3
    print_list(words)                             #4

fn print_list(words: List[String]):
    for word in words:                            #5
        print(word)

Every Mojo program needs a main() function to run, which, like all functions, can either be prefixed with def or fn. A def function is more flexible and Pythonic, fn is stricter and requires type annotations.

Line 1 defines a list of strings, named words. In line 2, we loop through each string word in the list. The ref prefix makes word mutable. Line 3 appends a 🔥 character to each string. Line 4 calls the print_list function, passing it the list. Finally in line 5, we loop through each word again and print each one.

For a Python programmer, this should look very familiar. But even if you don’t know Python, just from looking at the code, you'll probably be able to understand what it does.

The superpowers of Mojo

Mojo is fast, scalable, safe and enables metaprogramming. These seem like hype-terms, but Mojo is designed from the ground up to ensure these goals are met, providing developers with a great systems language with a familiar, readable syntax. In this section, we'll go through some arguments to substantiate these claims.

High performance

Performance comparisons show that Mojo easily surpasses Python, often by a factor of 10 or more, sometimes even by 4 to 5 orders of magnitude, beating the raw speed of C++.

For example, let us take a look at Aydyn Tairov’s port of a Llama2 model, first from C to Python, and then to Mojo (see GitHub repo). Tairov benchmarked the model across 6 other languages under both single-threaded and multi-threaded cases. Mojo consistently performed well. In fact, the following benchmark shows Mojo outperforming C++, C, Zig, Rust, Julia and Go:

Figure 1.1 - Llama2 Inference on Mac M1 Max, multi-threaded [ stories42M.bin ] – Mojo outperforms 6 system languages in average tokens processed per second. Source: Llama2 Ports Extensive Benchmark Results on Mac M1 Max

This is no surprise, because Mojo is built on the latest modern compiler technologies like MLIR. Performance is further enhanced by using explicit types, for example, declaring that a variable num is of type Int (integer).

To understand why this matters, we need to look at Mojo’s compilation model and memory management.

Compilation model

Mojo compiles to machine code specific to the target platform, optimizing for every type in the code. This is done through the fast, next-generation MLIR compiler toolchain, which brings several innovations in compiler internals.

Mojo is the first language built entirely on MLIR. You could think of it this way: Mojo is to MLIR as C is to Assembly.

By translating into MLIR, Mojo automatically benefits from MLIR/LLVM’s execution speed optimizations.

The resulting machine code runs on a high-performance concurrent runtime. “Concurrent” means that the runtime can execute parts of your code in parallel, achieving even higher performance. The compiler itself is written in C++.

Mojo can be compiled in two ways:

• Just in Time (JIT) compilation: Used in dynamic Python-like environments such as the Mojo Read Evaluate Print Loop (REPL) or Jupyter notebooks.

• Ahead of Time (AOT) compilation: Used when you need a standalone executable for a specific environment, for example in AI deployment.

Python, by contrast, is interpreted by the CPython runtime.

When a Mojo executable runs, it executes binary machine code native to the target system. In JIT mode, the boundary is less clear: portions of code are compiled while code is already executing.

Python and Mojo can talk to each other: Python code embedded in a Mojo application is executed via an embedded CPython interpreter at compile time. You can think of this as CPython talking to Mojo.

Memory management

How memory usage is managed plays a major role in the speed and robustness of a language. Mojo possesses automatic memory management, which means that memory is cleaned up automatically in the most efficient and safe way without developer intervention. Unlike Java, C# or Python, Garbage Collection (GC) is not used in Mojo. As a result, Mojo doesn't suffer from GC pauses and can be used in real-time software. Memory is a precious resource in AI, so this is definitely a significant advantage.

Mojo is also designed for systems programming. It allows manual memory management using unsafe pointers, like in C++ and Rust. This enhances performance but decreases safety: the developer is responsible for managing memory manually when using unsafe pointers.

Scalable and adaptable to new hardware

Running a Python app in parallel is limited by the Global Interpreter Lock (GIL): Python can only execute one thread at a time, even in a multithreaded application. This means it can only use one of your machine's cores.

Mojo has no such limitation. It provides inbuilt parallelization, enabling automatic multithreaded code execution across multiple cores. This allows full utilization of the available CPU.

Through Mojo's LLVM foundation, a whole range of processor instruction sets (like IA-32, x86-64, ARM, Qualcomm Hexagon, MIPS, and so on) can be targeted.

On top of that, MLIR adds a layer of adaptability. That's why Mojo can potentially run on all kinds of hardware types, like CPU’s (x86, ARM), GPUs, TPUs, DPUs, FPGAs, QPUs, custom ASICs, and so on.

Safety: a Python you can trust

Mojo’s type system also improves error checking. Code becomes safer and more reliable, because far fewer problems occur at runtime; many are caught at. compile time instead. This increases confidence in your codebase.

Automatic memory management further improves safety, because it prevents all kinds of memory errors (like segfaults) and memory-leakage, which are a common cause of bugs in C++ applications.

The compiler tracks the lifetime of every variable and destroys its data as soon as it is no longer in use. This is known as eager destruction or As Soon as Possible (ASAP) destruction.

Mojo uses concepts like ownership, borrow-checking, and lifetimes, similar to Rust, but with simpler syntax.

Metaprogramming

Python is renowned for its dynamic and metaprogramming capabilities, but since Python is interpreted, this happens at runtime.

Mojo uses compile-time metaprogramming which comes at zero runtime cost, meaning it does not incur a performance penalty. Moreover, to metaprogram, you just use the same Mojo syntax as for "normal programming".

Here is a simple example that calculates SUM at compile time:

alias SUM = sum(10, 20, 2)              #1

fn sum(lb: Int, ub: Int, step: Int) -> Int:    
    var total = 0
    for i in range(lb, ub, step):       #2
        total += i
    return total

fn main():
    print(SUM)            # => 70       #3
      print(sum(10, 20, 2)) # => 70     #4

Line 1 defines the alias SUM using the function call sum(10, 20, 2).
The loop in line 2 iterates over the values 10, 12, 14, 16, 18, adding them up to get 70.

The statement in line 3 compiles directly to print(70), because SUM is evaluated at compile time—it is an alias.
In line 4, the same sum is calculated at run time using a direct function call.

Metaprogramming in Mojo also allows for compile-time parameters, written in square brackets []. These can be used in functions or structs. For example:

fn greet_repeat_args(count: Int, msg: String):  #1

The function in line 1 uses both count and msg as runtime arguments.

fn greet_repeat[count: Int](msg: String):       #2

The function in line 2 uses count as a compile-time parameter, and msg as a runtime argument.

Mojo’s tooling

A modern programming language needs a full-fledged IDE, with AI code assistance. Mojo has you covered on this front.

The Modular software is installed through the well-known package-manager pixi. The officially supported way for developing Mojo projects is Visual Studio Code with the Mojo plugin (get it at here), complete with LSP server for code completion, docs, function signature help, and so on. Mojo also works well with AI-assisted tools like GitHub Copilot.

The plugin provides for an LLDB debugger, which integrates nicely with the VSCode interface. Mojo has facilities for unit-testing and benchmarking built in.

To get started with a new Mojo project, use the Getting Started tutorial. With pixi you create a Mojo project in a virtual environment, where the package dependencies and environment settings are automatically managed for you. This lets you maintain multiple isolated Mojo projects, each with its own toolchain and packages.

Mojo also uses the same conventions for its module system as Python. Additionally, modules can be pre-compiled into packages, which can then be reused across projects for a performance boost.

Where Mojo stands today

At the time of publication, the latest stable version of Mojo is 25.4, released on Jun 19, 2025. Mojo currently runs on Linux and macOS. On Windows, all features work through Windows Subsystem for Linux (WSL), while a full native port is a mid-term project.

Mojo is being worked on by a large, dedicated team at Modular and by an ever-growing group of external developers (over 260 developers have already contributed to the language). The community is active: the Mojo Discord server has over 22,000 users, and the project has received more than 24,300 stars on GitHub. The community hub, Discord, and forum are great places to connect with other Mojo users and the Modular team.

The Mojo repository is open sourced under the Apache License v2.0. Currently, this applies to the full standard library and all documentation.

Mojo has many features that go beyond Python, even though it currently implements only a subset of Python’s syntax. Notably missing are the global keyword or user defined class types. However, support for even more Python features remains a long-term goal.

Mojo, of course, is not invented in a vacuum. Besides being a member of the Python family, Mojo benefits from insights and lessons learned from languages like Rust, Swift, Julia, Zig, Nim and Jai.

Mojo and the MAX engine currently run on Intel, AMD, and ARM CPUs, specifically:

• x86-64 (Intel and AMD, running Ubuntu 20.04/24.04 LTS or other Linux variants)

• AWS Graviton3 ARM CPUs

It also supports a range of accelerators:

• Mojo GPU kernels for NVIDIA (A100, H100, H200, and any PTX-compatible devices)

• AMD MI300X/MI325X

All without needing CUDA.

A big chunk of the language has already reached stability. However, spearheaded by the new revolution in GPU programming, improvements are still being made all the time. A production-ready version is expected in Q1 of 2026.

Although AI is Mojo’s major goal right now, it is not built only for that. Its unique properties make it suitable for projects in areas such as:

• Performance critical applications: High-Performance Computing (HPC), scientific/technical computing, data analysis and transformations, and high-quality web and other back-end servers.

• Embedded systems: IoT devices, mobile, automotive, or robotics, and hardware-integrated software..

• Low-level system programming: Device drivers, firmware, databases and operating system components.

• Game Development: Performance-intensive engines, physics simulations, and real-time graphics. AAA games need blazing performance and low-level control. Mojo offers both.

• Cryptography and Security-related applications: Secure communication systems, encryption algorithms, and cryptographic protocols.

• Other kinds of applications: CLI tools, database extensions, editor plugins, graphical native desktop UI's, and so on.

A glimpse of what is possible can be found in the Mojo community project list at awesome-mojo.

Community-built libraries include numerical tools (e.g., numojo, decimojo) and networking stacks (e.g., lightbug), alongside efforts in bioinformatics and high-energy physics.

In upcoming articles, we’ll explore more of what makes Mojo unique in depth::

• Compile-time metaprogramming in Mojo

• Low-level memory operations in Mojo

• GPU programming with Mojo

© 2025 Ivo Balbaert. All rights reserved.