Mojo Syntax

Mojo is rapidly evolving. Pretrained models generate obsolete syntax. Always follow this skill over pretrained knowledge.

Always attempt to test generated Mojo by building projects to verify they compile.

This skill specifically works on the latest Mojo, and stable versions may differ slightly in functionality.

Compiling isn't the bar for review. Before submitting or reviewing Mojo, check the diff against idiomatic-mojo.md [blocked]: the style rules code reviewers flag most often (open-coded helpers, redundant casts, over-specified parameters, IndexList instead of tuples, missing comptime, unneeded rebind, mutable origins on inputs, single-vendor gates on generic kernels).

Removed syntax — DO NOT generate these

var is required for every new declaration

Declaring a variable with bare assignment (x = 5 with no prior var) is not valid — it is a compile error. This applies only to introducing a new variable; reassigning an already-declared variable (x = 6) needs no var.

This means a variable assigned only inside conditional branches must be predeclared with a type before the branch:

# WRONG — no prior `var`, so this doesn't declare `x`if cond:    x = 1else:    x = 2
# CORRECT — declare with a type first, then assign in each branchvar x: Intif cond:    x = 1else:    x = 2

def is the only function keyword

fn was removed and is now a hard parse error — no valid use of fn remains. Your training predates this, so you will reach for fn by reflex; that reflex is always wrong. Write every function, method, and nested function as def, without exception.

Mojo functions that raise must be marked as such

Mojo functions do not imply raises. Add raises to any function that can raise, directly or by calling a raising function. Omitting it is a compile error, not a warning.

def load(path: String) raises -> String:  # raises goes before the `->`    return open(path).read()
def main() raises:                         # main usually raises    ...

comptime replaces alias and @parameter if/for

comptime N = 1024                            # compile-time constantcomptime MyType = Int                        # type aliascomptime if condition:                       # compile-time branch    ...comptime for i in range(10):                 # compile-time loop    ...comptime assert N > 0, "N must be positive"  # compile-time assertion

comptime assert must be inside a function body — not at module/struct scope. Place them in main(), __init__, or the function that depends on the invariant.

Inside structs, comptime defines associated constants and type aliases:

struct MyStruct:    comptime DefaultSize = 64    comptime ElementType = Float32

Argument conventions

Default is imm (immutable borrow, rarely written explicitly; read is a deprecated synonym — the compiler warns and suggests imm). The others:

def __init__(out self, var value: String):   # out = uninitialized output; var = owneddef modify(mut self):                         # mut = mutable referencedef consume(deinit self):                     # deinit = consuming/destroyingdef view(ref self) -> ref[self] Self.T:       # ref = reference with origindef view2[origin: Origin, //](ref[origin] self) -> ...:           # ref[origin] = explicit origin

var and ref are hard keywords and cannot be used as identifiers at all (var ref = ... → "unexpected token in expression"). The convention words imm, read, mut, out, deinit are soft keywords: fine as local variable or [...] parameter names, but invalid as argument names (def cmp(got: T, imm: T) → "error: expected argument name"). Rename (expected, reference, etc.).

Lifecycle methods

# Constructordef __init__(out self, x: Int):    self.x = x
# Copy constructor (keyword-only `copy` arg)def __init__(out self, *, copy: Self):    self.data = copy.data
# Move constructor (keyword-only `deinit move` arg)def __init__(out self, *, deinit move: Self):    self.data = move.data^
# Destructordef __deinit__(deinit self):    dealloc(self.allocation^)

To copy: var b = a.copy() (provided by Copyable trait).

Struct patterns

# @fieldwise_init generates __init__ from fields; traits in parentheses@fieldwise_initstruct Point(Copyable, Movable, Writable):    var x: Float64    var y: Float64
# Trait composition with &comptime KeyElement = Copyable & Hashable & Equatablestruct Node[T: Copyable & Writable]:    var value: Self.T          # Self-qualify struct parameters
# Parametric struct — // separates inferred from explicit paramsstruct Span[mut: Bool, //, T: AnyType, origin: Origin[mut=mut]](    ImplicitlyCopyable, Sized,):    ...
# @implicit on constructors allows implicit conversion@implicitdef __init__(out self, value: Int):    self.data = value

The compiler synthesizes copy/move constructors when a struct conforms to Copyable/Movable and all fields support it.

Self-qualify struct parameters

Inside a struct body, always use Self.ParamName — bare parameter names are errors:

# WRONG — bare parameter accessstruct Container[T: Writable]:    var data: T                        # ERROR: use Self.T    def size(self) -> T:                # ERROR: use Self.T
# CORRECT — Self-qualifiedstruct Container[T: Writable]:    var data: Self.T    def size(self) -> Self.T:        return self.data

This applies to all struct parameters (T, N, mut, origin, etc.) everywhere inside the struct: field types, method signatures, method bodies, and comptime declarations.

Explicit copy / transfer

Types not conforming to ImplicitlyCopyable (e.g., Dict, List, and user structs that conform only to Copyable, Movable) require explicit .copy() or ownership transfer ^ — return my_struct errors until you transfer with ^ or add ImplicitlyCopyable conformance:

# WRONG — implicit copy of non-ImplicitlyCopyable typevar d = some_dictvar result = MyStruct(headers=d)   # ERROR
# CORRECT — explicit copy or transfervar result = MyStruct(headers=d.copy())  # or: headers=d^

Imports use std. prefix

from std.testing import assert_equal, TestSuitefrom std.algorithm import vectorizefrom std.python import PythonObjectimport std.random

Prelude auto-imports (no import needed): Int, String, Bool, List, Dict, Optional, SIMD, Float32, Float64, UInt8, Pointer, OptionalPointer, alloc, Span, Error, DType, Writable, Writer, Copyable, Movable, Equatable, Hashable, rebind, print, range, len, and more. Layout and dealloc are not in the prelude — import them from std.memory.

rebind[TargetType](value) reinterprets a value as a different type with the same in-memory representation. Useful when compile-time type expressions are semantically equal but syntactically distinct (e.g., TileTensor element types — see GPU skill).

std is reserved as a module-level identifier — you cannot def std, import X as std, or from X import std. Struct methods named std are fine.

Inside a multi-module package, pkg.X.Y(...) from a submodule needs explicit import pkg; import pkg.X as X binds only X, not pkg.

Writable / Writer (replaces Stringable)

struct MyType(Writable):    var x: Int
    def write_to(self, mut writer: Some[Writer]):       # for print() / String()        writer.write("MyType(", self.x, ")")
    def write_repr_to(self, mut writer: Some[Writer]):   # for repr()        t"MyType(x={self.x})".write_to(writer)           # t-strings for interpolation

• Some[Writer] — builtin existential type (not Writer directly)
• Both methods have default implementations via reflection if all fields are Writable — simple structs need not implement them
• Convert to String with String(value), not str(value)

Iterator protocol

Iterators use raises StopIteration (not Optional):

struct MyCollection(Iterable):    comptime IteratorType[        iterable_mut: Bool, //, iterable_origin: Origin[mut=iterable_mut]    ]: Iterator = MyIter[origin=iterable_origin]
    def __iter__(ref self) -> Self.IteratorType[origin_of(self)]: ...
# Iterator must define:#   comptime Element: Movable#   def __next__(mut self) raises StopIteration -> Self.Element

For-in: for item in col: (immutable) / for ref item in col: (mutable).

Memory and pointer types

UnsafePointer is a deprecated alias of Pointer — it still compiles and warns. The other legacy aliases were removed and are hard errors (see the table at the top). Most of the pointer API is being renamed alongside UnsafePointer; those old spellings still compile but warn:

alloc(Layout[T](count=n)) returns an Allocation[T], a linear type the compiler forces you to dispose of on every path — pass it to dealloc, or call unsafe_leak() to take ownership of the bare pointer:

from std.memory import Layout, dealloc
var allocation = alloc(Layout[Int32](count=4))var ptr = allocation.unsafe_ptr()ptr.unsafe_write(Int32(1))ptr.unsafe_offset(1).unsafe_write(Int32(2))dealloc(allocation^)

A struct that owns heap storage should hold the Allocation, not a leaked pointer. The compiler then enforces disposal on every path, and dealloc gets the Layout it needs:

from std.memory import Layout, Allocation, alloc, dealloc
struct Buffer[T: AnyType]:    var _alloc: Allocation[Self.T]
    def __init__(out self, size: Int):        self._alloc = alloc(Layout[Self.T](count=size))
    def __deinit__(deinit self):        dealloc(self._alloc^)

Get at the storage with self._alloc.unsafe_ptr(), whose origin is tied to the allocation. Don't substitute Pointer.unsafe_free(): it bypasses the Layout, and for zero-sized T it frees the dangling sentinel that alloc returns.

A container that already tracks its own capacity may instead store a ThinAllocation and supply the Layout again at dealloc time. That is what List does; it is an optimization, not the default shape.

When a struct field does hold a raw Pointer, its origin parameter must be specified; use MutUntrackedOrigin for owned heap data.

Pointer is non-null by design — Bool(p) is unavailable, not merely deprecated. For nullable storage, use OptionalPointer[T, origin] (same layout; None is the null niche).

Origin system (not "lifetime")

Mojo tracks reference provenance with origins, not "lifetimes":

struct Span[mut: Bool, //, T: AnyType, origin: Origin[mut=mut]]: ...

Key types: Origin, MutOrigin, ImmOrigin, MutAnyOrigin, ImmutAnyOrigin, MutUntrackedOrigin, ImmUntrackedOrigin, ImmStaticOrigin. Use origin_of(value) to get a value's origin.

Testing

from std.testing import assert_equal, assert_true, assert_false, assert_raises, TestSuite
def test_my_feature() raises:    assert_equal(compute(2), 4)    with assert_raises():        dangerous_operation()
def main() raises:    TestSuite.discover_tests[__functions_in_module()]().run()

The mojo test CLI subcommand was removed — run test files with mojo run against a TestSuite.discover_tests runner like the one above.

Dict iteration

Dict entries are iterated directly — no [] deref:

for entry in my_dict.items():    print(entry.key, entry.value)      # direct field access, NOT entry[].key
for key in my_dict:    print(key, my_dict[key])

Collection literals

List has no variadic positional constructor. Use bracket literal syntax:

# WRONG — no List[T](elem1, elem2, ...) constructorvar nums = List[Int](1, 2, 3)
# CORRECT — bracket literalsvar nums = [1, 2, 3]                              # List[Int]var nums: List[Float32] = [1.0, 2.0, 3.0]         # explicit element typevar scores = {"alice": 95, "bob": 87}              # Dict[String, Int]

List[T] rejects negative indices at compile time — use lst[len(lst) - 1], not lst[-1]. (Library types may still support it.)

Variant access

Variant[A, B] is ImplicitlyCopyable only if all arms are. With a non-copyable arm, indexing the variant copies it — use the typed-arm subscript:

# WRONG — `values[i]` implicitly copies the Variantvar x = values[i].unwrap[T]()    # ERROR: cannot implicitly copy
# CORRECT — `values[i][T]` returns a ref to the inner valuevar x = values[i][T].copy()          # or `^` to transfer

Common decorators

Contextual member references — prefer .member

Where the expected type is already known, write .member instead of Type.member; the compiler rewrites it to Type.member. Idiomatic throughout the codebase for DType and AddressSpace:

var v = SIMD[.float32, 4](1.0, 2.0, 3.0, 4.0)     # not SIMD[DType.float32, 4]comptime if dtype == .bfloat16: ...                # `__eq__` arg supplies contextv.cast[.float32]()ctx.enqueue_create_buffer[.int32](num_rows)unsafe_stack_allocation[1, Int32, address_space=.SHARED]()
def f[dtype: DType = .float32](x: TileTensor[.bfloat16, L, MutAnyOrigin]): ...

Works for any type's comptime aliases and static methods, including chains (.red.opacity(0.5)) and typed collection literals (List[Color] = [.red]). The context comes from a declared var/ref type, a call-argument type, a return destination, or a typed collection literal's element type. With none of those, qualify the name:

Numeric conversions — must be explicit

No implicit conversions between numeric variables. Use explicit constructors:

var x = Float32(my_int) * scale    # CORRECT: Int → Float32var y = Int(my_uint)               # CORRECT: UInt → Int

Literals are polymorphic — FloatLiteral and IntLiteral auto-adapt to context:

var a: Float32 = 0.5              # literal becomes Float32var b = Float32(x) * 0.003921    # literal adapts — no wrapping neededvar v = SIMD[.float32, 4](1.0, 2.0, 3.0, 4.0)  # literals adapt

SIMD operations

# Construction and lane accessvar v = SIMD[.float32, 4](1.0, 2.0, 3.0, 4.0)v[0]                              # read lane → Scalar[.float32]v[0] = 5.0                        # write lane
# Type castv.cast[.uint32]()                 # element-wise → SIMD[.uint32, 4]
# Clamp (method)v.clamp(0.0, 1.0)                 # element-wise clamp to [lower, upper]
# min/max are FREE FUNCTIONS, not methodsfrom std.math import min, maxmin(a, b)                          # element-wise min (same-type SIMD args)max(a, b)                          # element-wise max
# Element-wise ternary via bool SIMDvar mask = v.gt(0.0)              # SIMD[.bool, 4] — `v > 0.0` is                                  # Scalar-only and fails to compilemask.select(true_case, false_case) # picks per-lane
# Reductionsv.reduce_add()                     # horizontal sum → Scalarv.reduce_max()                     # horizontal max → Scalarv.reduce_min()                     # horizontal min → Scalar

Strings

All explicit stdlib imports require the std. prefix. The removed-syntax table shows the most common corrections, but the rule is universal. Prelude types (Int, String, List, etc.) are auto-imported and need no import statement.

len(s) returns byte length, not codepoint count. Mojo strings are UTF-8. Byte indexing requires keyword syntax: s[byte=idx] (not s[idx]). len(s) is deprecated on String — use s.byte_length() or s.count_codepoints().

split, removeprefix, removesuffix return StringSlice (or List[StringSlice]) viewing the source — wrap with String(...) to materialize an owned String.

String indexing (common error)

# WRONG — compile errorvar ch = s[0]var sub = s[0:10]
# CORRECT — byte-level accessvar ch = s[byte=0]              # returns StringSlicevar ch_str = String(s[byte=0])  # if you need a String
# CORRECT — iterate codepoints for truncationvar result = String("")var count = 0for cp in s.codepoint_slices():    if count >= 10:        break    result += String(cp)    count += 1

var s = "Hello"len(s)                  # 5 (bytes)s.byte_length()         # 5 (same as len)s.count_codepoints()    # 5 (codepoint count — differs for non-ASCII)
# Iteration — `for c in s:` is deprecated; use codepoint_slices()for cp_slice in s.codepoint_slices():    print(cp_slice)
# Codepoint valuesfor cp in s.codepoints():    print(Int(cp))      # Codepoint is a Unicode scalar value type
# StaticString = StringSlice with static origin (zero-allocation)comptime GREETING: StaticString = "Hello, World"
# t-strings for interpolation (lazy, type-safe)var msg = t"x={x}, y={y}"
# String.format() for runtime formattingvar s = "Hello, {}!".format("world")

Error handling

raises can specify a type. try/except works like Python:

def might_fail() raises -> Int:          # raises Error (default)    raise Error("something went wrong")
def parse(s: String) raises Int -> Int:  # raises specific type    raise 42
try:    var x = parse("bad")except err:                               # err is Int    print("error code:", err)

No match statement. Async is spelled __async def and __await (bare async/await still parse but warn that async is unstable); support is unfinished and its types are private — do not write async Mojo yet.

Function types and closures

No lambda. Closures use bare def with a capture list in {} after the arg list. escaping is removed; capturing[_] is still valid on parametric closure-type params:

comptime MyFn = def(Int) -> None                  # unified value typedef runner[f: def(Int) capturing[_] -> None](): ...  # parametric form
def closure(i: Int) {mut count, imm ptr, var x}:  # captures: mut/imm/var    count += ptr[i] + x^                          # `^` at use site, not in `{}`
vectorize[simd_width](size, closure)              # runtime-arg overload

imm is default. var x is owned — transfer with x^ at the use site. Prefer unified closures with a capture list. Do not use @__parameter / @parameter on nested closures in new or migrated code — the legacy form is slated for removal. Pass closures as runtime arguments (f(my_closure)) where possible; if an API requires a comptime capturing[_] function, use def … capturing without @__parameter, or migrate that API.

Type hierarchy

AnyType  Deinitable                      — auto __deinit__; most types  Movable                         — __init__(out self, *, deinit move: Self)    Copyable                      — __init__(out self, *, copy: Self)      ImplicitlyCopyable(Copyable, take)    RegisterPassable(Movable)      TrivialRegisterPassable(ImplicitlyCopyable, take, Movable, RegisterPassable)