OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add modular/skills --skill mojo-syntax
Help to write Mojo code using current syntax and conventions. Always use this skill when writing any Mojo code, including when other Mojo-specific skills (e.g., mojo-gpu-fundamentals) also apply. Use when writing Mojo code, translating projects to Mojo, or otherwise generating Mojo. Use this skill to overcome misconceptions with how Mojo is written.
npx skills add modular/skills --skill 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.
| Removed | Replacement |
|---|---|
alias X = ... | comptime X = ... |
@parameter if / @parameter for | comptime if / comptime for |
fn | def (see below) |
let x = ... | var x = ... (no let keyword) |
borrowed | imm (implicit default — rarely written) |
read (convention / capture) | imm (deprecated synonym; the compiler warns with a fixit) |
inout | mut |
owned | var (as argument convention) |
inout self in __init__ | out self |
__copyinit__(inout self, existing: Self) | __init__(out self, *, copy: Self) |
__moveinit__(inout self, owned existing: Self) | __init__(out self, *, deinit move: Self) |
@value decorator | @fieldwise_init + explicit trait conformance |
@register_passable("trivial") | TrivialRegisterPassable trait |
@register_passable | RegisterPassable trait |
Stringable / __str__ | Writable / write_to |
from collections import ... | from std.collections import ... |
from memory import ... | from std.memory import ... |
from sys import ... | from std.sys import ... |
from os import ... | from std.os import ... |
from pathlib import ... | from std.pathlib import ... |
s[i] | s[byte=i] — returns StringSlice; wrap in String() if needed |
s[0:10], s[:5] | No slice syntax on String — use s.codepoint_slices() or Python FFI |
constrained(cond, msg) | comptime assert cond, msg |
DynamicVector[T] | List[T] |
InlinedFixedVector[T, N] | Array[T, N] |
Tensor[T] | Not in stdlib (use SIMD, List, Pointer) |
MutUnsafePointer / ImmUnsafePointer | MutPointer / ImmPointer |
OptionalUnsafePointer | OptionalPointer |
escaping closures | Unified closures (def(...) -> T, captures in {}); capturing[_] still valid |
__del__(deinit self) | __deinit__(deinit self) |
var is required for every new declarationDeclaring 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:
def is the only function keywordfn 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 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.
comptime replaces alias and @parameter if/forcomptime 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:
Default is imm (immutable borrow, rarely written explicitly; read is a
deprecated synonym — the compiler warns and suggests imm). The others:
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.).
To copy: var b = a.copy() (provided by Copyable trait).
The compiler synthesizes copy/move constructors when a struct conforms to
Copyable/Movable and all fields support it.
Inside a struct body, always use Self.ParamName — bare parameter names are
errors:
This applies to all struct parameters (T, N, mut, origin, etc.)
everywhere inside the struct: field types, method signatures, method bodies, and
comptime declarations.
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:
std. prefixPrelude 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)Some[Writer] — builtin existential type (not Writer directly)Writable — simple structs need not implement themString with String(value), not str(value)Iterators use raises StopIteration (not Optional):
For-in: for item in col: (immutable) / for ref item in col: (mutable).
| Type | Use |
|---|---|
Pointer[T, mut=M, origin=O] | Safe, non-nullable. Deref with p[]. |
OptionalPointer[T, origin] | Nullable pointer — Optional[Pointer[...]]. |
Allocation[T] | Owning handle returned by alloc. Explicitly destroyed. |
Span(list) | Non-owning contiguous view. |
OwnedPointer[T] | Unique ownership (like Rust Box). |
ArcPointer[T] | Reference-counted shared ownership. |
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:
| Deprecated | Replacement |
|---|---|
UnsafePointer[T, O] | Pointer[T, O] |
alloc[T](n) | alloc(Layout[T](count=n)) |
p.free() | dealloc(allocation^) |
p[i] | p[unsafe_offset=i] |
p + i | p.unsafe_offset(i) |
p += i | p = p.unsafe_offset(i) |
p.load() / p.store(v) | p.unsafe_load() / p.unsafe_store(v) |
p.init_pointee_move(v) | p.unsafe_write(v) |
p.init_pointee_copy(v) | p.unsafe_write(copy=v) |
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:
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:
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).
Mojo tracks reference provenance with origins, not "lifetimes":
Key types: Origin, MutOrigin, ImmOrigin, MutAnyOrigin,
ImmutAnyOrigin, MutUntrackedOrigin, ImmUntrackedOrigin,
ImmStaticOrigin. Use origin_of(value) to get a value's origin.
The mojo test CLI subcommand was removed — run test files with mojo run
against a TestSuite.discover_tests runner like the one above.
Dict entries are iterated directly — no [] deref:
List has no variadic positional constructor. Use bracket literal syntax:
List[T] rejects negative indices at compile time — use lst[len(lst) - 1],
not lst[-1]. (Library types may still support it.)
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:
| Decorator | Purpose |
|---|---|
@fieldwise_init | Generate fieldwise constructor |
@implicit | Allow implicit conversion |
@inline(.always) / @inline(.nodebug) | Force inline |
@inline(.never) | Prevent inline |
@staticmethod | Static method |
@deprecated("msg") | Deprecation warning |
@doc_hidden | Hide from docs |
@explicit_destroy | Linear type (no implicit destruction) |
No implicit conversions between numeric variables. Use explicit constructors:
Literals are polymorphic — FloatLiteral and IntLiteral auto-adapt to
context:
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.
raises can specify a type. try/except works like Python:
No match statement. async def and await parse, but async support is
unfinished and its types are private — do not write async Mojo yet.
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:
imm is default. var x is owned — transfer with x^ at the use site.
Prefer unified closures with a capture list. Do not under any circumstance
use @__parameter / @parameter on nested closures — that legacy form is
forbidden in new and migrated code (not a temporary bridge, not an
imm-borrow helper, not a still-capturing API workaround). Pass closures as
runtime arguments (f(my_closure)) rather than comptime parameters when
possible. If an API still requires a comptime capturing[_] function, use
def … capturing without @__parameter, or migrate that API — never put
@__parameter on the caller.
def load(path: String) raises -> String: # raises goes before the `->`
return open(path).read()
def main() raises: # main usually raises
...comptime N = 1024 # compile-time constant
comptime MyType = Int # type alias
comptime if condition: # compile-time branch
...
comptime for i in range(10): # compile-time loop
...
comptime assert N > 0, "N must be positive" # compile-time assertionstruct MyStruct:
comptime DefaultSize = 64
comptime ElementType = Float32def __init__(out self, var value: String): # out = uninitialized output; var = owned
def modify(mut self): # mut = mutable reference
def consume(deinit self): # deinit = consuming/destroying
def view(ref self) -> ref[self] Self.T: # ref = reference with origin
def view2[origin: Origin, //](ref[origin] self) -> ...: # ref[origin] = explicit origin# Constructor
def __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^
# Destructor
def __deinit__(deinit self):
dealloc(self.allocation^)# @fieldwise_init generates __init__ from fields; traits in parentheses
@fieldwise_init
struct Point(Copyable, Movable, Writable):
var x: Float64
var y: Float64
# Trait composition with &
comptime KeyElement = Copyable & Hashable & Equatable
struct Node[T: Copyable & Writable]:
var value: Self.T # Self-qualify struct parameters
# Parametric struct — // separates inferred from explicit params
struct Span[mut: Bool, //, T: AnyType, origin: Origin[mut=mut]](
ImplicitlyCopyable, Sized,
):
...
# @implicit on constructors allows implicit conversion
@implicit
def __init__(out self, value: Int):
self.data = value# WRONG — bare parameter access
struct Container[T: Writable]:
var data: T # ERROR: use Self.T
def size(self) -> T: # ERROR: use Self.T
# CORRECT — Self-qualified
struct Container[T: Writable]:
var data: Self.T
def size(self) -> Self.T:
return self.data# WRONG — implicit copy of non-ImplicitlyCopyable type
var d = some_dict
var result = MyStruct(headers=d) # ERROR
# CORRECT — explicit copy or transfer
var result = MyStruct(headers=d.copy()) # or: headers=d^from std.testing import assert_equal, TestSuite
from std.algorithm import vectorize
from std.python import PythonObject
import std.randomstruct 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 interpolationstruct 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.Elementfrom 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^)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^)struct Span[mut: Bool, //, T: AnyType, origin: Origin[mut=mut]]: ...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()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])# WRONG — no List[T](elem1, elem2, ...) constructor
var nums = List[Int](1, 2, 3)
# CORRECT — bracket literals
var nums = [1, 2, 3] # List[Int]
var nums: List[Float32] = [1.0, 2.0, 3.0] # explicit element type
var scores = {"alice": 95, "bob": 87} # Dict[String, Int]# WRONG — `values[i]` implicitly copies the Variant
var x = values[i].unwrap[T]() # ERROR: cannot implicitly copy
# CORRECT — `values[i][T]` returns a ref to the inner value
var x = values[i][T].copy() # or `^` to transfervar x = Float32(my_int) * scale # CORRECT: Int → Float32
var y = Int(my_uint) # CORRECT: UInt → Intvar a: Float32 = 0.5 # literal becomes Float32
var b = Float32(x) * 0.003921 # literal adapts — no wrapping needed
var v = SIMD[DType.float32, 4](1.0, 2.0, 3.0, 4.0) # literals adapt# Construction and lane access
var v = SIMD[DType.float32, 4](1.0, 2.0, 3.0, 4.0)
v[0] # read lane → Scalar[DType.float32]
v[0] = 5.0 # write lane
# Type cast
v.cast[DType.uint32]() # element-wise → SIMD[DType.uint32, 4]
# Clamp (method)
v.clamp(0.0, 1.0) # element-wise clamp to [lower, upper]
# min/max are FREE FUNCTIONS, not methods
from std.math import min, max
min(a, b) # element-wise min (same-type SIMD args)
max(a, b) # element-wise max
# Element-wise ternary via bool SIMD
var mask = (v > 0.0) # SIMD[DType.bool, 4]
mask.select(true_case, false_case) # picks per-lane
# Reductions
v.reduce_add() # horizontal sum → Scalar
v.reduce_max() # horizontal max → Scalar
v.reduce_min() # horizontal min → Scalar# WRONG — compile error
var ch = s[0]
var sub = s[0:10]
# CORRECT — byte-level access
var ch = s[byte=0] # returns StringSlice
var ch_str = String(s[byte=0]) # if you need a String
# CORRECT — iterate codepoints for truncation
var result = String("")
var count = 0
for cp in s.codepoint_slices():
if count >= 10:
break
result += String(cp)
count += 1var 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 values
for 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 formatting
var s = "Hello, {}!".format("world")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)comptime MyFn = def(Int) -> None # unified value type
def 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 overloadAnyType
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)