What Zig 0.17.x changed, and the rules that keep Zig correct under failure, concurrency, and later change. The facts were checked against the 0.17.0 and 0.17.1 standard library and compiler and a real 0.16 to 0.17 port. Trust them and the bundled scripts; read std source only for an API this skill lacks.
Repository instructions (AGENTS.md and similar), build.zig, and
build.zig.zon come first and override this skill. Keep established patterns
unless they cause a correctness, safety, or ownership defect. For another Zig
release, use only the version-independent references and check std in its source.
Check the compiler first
Read .minimum_zig_version in build.zig.zon and run zig version. Neither
0.16 nor 0.17 enforces that field, so a wrong compiler fails late and misleadingly.
- 0.16 on a 0.17 project: do not build with it. It reports correct code as
broken (
no field or member function named 'print' in 'mem.Allocator',no field named 'debug' in enum 'builtin.OptimizeMode'); never "fix" that back to 0.16 names. Find a 0.17 compiler withwhich -a zigand in versioned install directories, and run it by absolute path orPATH=<dir>:$PATH. - 0.17.0 and 0.17.1: the language and LLVM 22.1.8 are the same, but 0.17.1
fixes miscompilations, changes a few std signatures, and changes two
behaviors silently: ending a
std.httprequest that sent a body now reads its unread answer to the end, and-femit-llvm-bcis now optimized. Build and test with the pinned patch release; toolchain lists what 0.17.1 fixed and still breaks. - Never upgrade, relink, or replace a shared
zig. Install a missing release next to the others, or ask, and say which checks did not run on it.
Working method
Before editing, map the contract: ownership, borrowing, lifetimes, allocation, errors, external bounds, thread ownership, and build-mode assumptions. Make invalid states hard to express with enums, tagged unions, optionals, and named error sets. Keep allocation, blocking I/O, mutation, and ownership transfer visible in signatures or doc comments. Make the smallest coherent change, and do not widen a shared contract for one caller. These are correctness issues, not style:
- Every allocation has one owner and a cleanup path on success and failure.
- No pointer or slice outlives its storage or survives a mutation that can reallocate it.
- External lengths, offsets, counts, recursion, retries, queues, and captured output are validated and bounded before arithmetic, allocation, or slicing.
- Assertions and
catch unreachableguard program-owned invariants only; malformed external data gets normal error handling in every build mode. - Integer conversions and arithmetic have stated range and overflow reasoning.
- Shared mutable state has an owner and a synchronization policy, and cancellation or shutdown leaves no thread or resource behind.
- Public contracts state ownership and do not expose
anyerror,anytype, or internal mutable storage by accident.
Changes that compile but change behavior
A clean build proves none of these. Check every one during a migration.
@hasDeclonly seespubdeclarations, even in the same file, so a probe of a private one silently turns a feature off. Make itpub.std.mem.containsAtLeastScalar(T, list, element, minimum)swapped its last two parameters (0.16:minimum, element); oldu8calls compile and answer wrongly. SlicecontainsAtLeastkeeps(haystack, count, needle).@bitCastwas redefined. Array and vector casts concatenate logical bit representations (endian-agnostic).extern struct/extern unionoperands are rejected; pun through@as(*align(1) const T, @ptrCast(&value)). A cast to an enum safety-checks the tag.@tagName(builtin.optimize)yieldsdebug,safe,fast,small; map it when a user sees the label.std.mem.eqlandfindDiffon floats no longer treat a slice as equal to itself (NaN is not equal to NaN).std.array_list.Managed(and sostd.json.Array) has a requiredpointer_stabilityfield: use.init(gpa)or.fromOwnedSlice(gpa, items).
Removed: these no longer compile
| 0.16 | 0.17 |
|---|---|
[1]T{v} ** n, "ab" ** n |
const a: [n]T = @splat(v);; repeated strings need a comptime helper (language) |
errdefer |err| ... |
Split the function and handle the error in the caller |
void{}, i0 |
{}, u0 |
@cImport |
The translate-c package (build system) |
opt == .ReleaseSafe and the other old tags in == or != |
.debug, .safe, .fast, .small |
std.heap.StackFallbackAllocator, stackFallback |
std.heap.BufferFirstAllocator.init(buffer, fallback) |
@typeInfo(T).@"struct".fields |
.field_names, .field_types, .field_attrs, .decl_names |
b.build_root, if (b.args) |a| run.addArgs(a) |
b.root (a Cache.Path), run.addPassthruArgs() |
The full list, with std.ascii, bit sets, packed ints, and ZON, is in std.
Deprecated: still compiles, do not write it
| Deprecated | Use |
|---|---|
std.fmt.allocPrint(gpa, f, a) |
gpa.print(f, a) (same error set) |
std.fmt.bufPrint, bufPrintSentinel, BufPrintError |
std.mem.print, std.mem.printSentinel, std.mem.PrintError |
std.mem.indexOf*, lastIndexOf* |
std.mem.find, findScalar, findAny, findPos, findLast, findScalarLast, findLastAny |
std.mem.copyForwards(T, d, s), copyBackwards |
@memmove(d[0..s.len], s); @memmove requires equal lengths |
anything in std.fs |
std.Io.Dir.path, std.Io.Dir.max_path_bytes, std.Io.Dir.max_name_bytes |
path.resolve, path.relative |
std.Io.Dir.path.resolveAlloc, relativeAlloc |
@import("builtin").os, .cpu, .abi, .object_format |
builtin.target.os, .target.cpu, .target.abi, .target.ofmt |
builtin.mode, std.debug.runtime_safety |
builtin.optimize, builtin.optimize.runtimeSafety() |
std.builtin, std.lang.OptimizeMode |
std.lang, std.lang.Optimize |
@intFromEnum, @enumFromInt |
@backingInt, @fromBackingInt (zig fmt rewrites them) |
std.ArrayListUnmanaged, *ArrayHashMapUnmanaged, *BitSet* |
std.ArrayList, std.array_hash_map.String/Auto/Custom, std.bit_set.Integer/Array/Static/Dynamic |
list.getLast(), getLastOrNull() |
list.last().?, list.last() |
std.heap.DebugAllocator (deprecated) |
std.heap.SafeAllocator |
std.unicode.utf8Decode |
Validate with utf8ByteSequenceLength, then utf8Decode2/3/4 |
std.meta.fieldNames, fieldInfo, fieldTypes |
@typeInfo |
Run addArtifactArg, addFileArg, addPrefixed*Arg, ... |
addArtifactArg2(x, .{ .prefix = "-p" }), addFileArg2, ... |
b.addTranslateC |
The translate-c package |
Most rows forward to their replacement, so the rename cannot change behavior.
Three can: copyForwards (lengths), utf8Decode (validation), and
DebugAllocator, which is not an alias of SafeAllocator. Rarer deprecations
are in std.
Entry point, I/O, and allocators
pub fn main(init: std.process.Init) !void {
const greeting = try init.gpa.print("hello, {s}", .{"zig"});
defer init.gpa.free(greeting);
var buffer: [4096]u8 = undefined;
var stdout = std.Io.File.stdout().writer(init.io, &buffer);
try stdout.interface.print("{s}\n", .{greeting});
try stdout.interface.flush();
}
init.gpais astd.heap.SafeAllocatorin Debug and ReleaseSafe builds and reports leaks whenmainreturns, without changing the exit code. Other builds getstd.heap.c_allocatorwhen linking libc andsmp_allocatorotherwise. Do not hand-build that switch.init.iois astd.Io.Threaded: pass it down instead of creating another.init.arenalives until exit;init.environ_mapandinit.minimal.argshold the environment and arguments.pub fn main() !voidgets neither.- Pick allocators by lifetime:
std.testing.allocatorin tests,SafeAllocatorfor leak checks (never in production: it never reuses memory), anArenaAllocatorper request or batch,FixedBufferAllocatorfor bounded scratch, andstd.heap.smp_allocatorfor shared concurrent use. std.Io.Eventeddoes not compile on 0.17.0 or 0.17.1; usestd.Io.Threaded.std.ArrayList(T)starts as.emptyand takes the allocator per call. Growth can move storage: take interior pointers after reserving capacity.- Reading
undefinedis illegal behavior. Narrow withstd.math.cast; use@intCastonly after the range is proven. Locks,Child.Term, and cancellation are in io-concurrency-security.
Writing, migrating, and reviewing
New code: use only the right-hand columns above, and before reporting it done, require exit 0 from the scanner (no finding to fix, every path read):
python3 <this skill>/scripts/check_deprecated.py <files or directories>
Migrating 0.16 code:
-
Read toolchain first if CI, release targets, or OS minimums change.
-
Apply the mechanical renames, then let
zig fmt(0.17) rewrite@intFromEnumand@enumFromInt:python3 <this skill>/scripts/migrate.py --write <files or directories> zig fmt <files or directories>scripts/migrate.pyonly makes exact forwarding renames outside strings and comments, prints aNOTEwhere judgment is needed, never writes through a link, and without--writeonly reports. -
Zig analyzes lazily: build every artifact the project ships and run the full test suite.
-
Run
check_deprecated.py --review, replace what remains, and read every review hotspot against the six behavior changes above. Rewrite eachcopyForwardssite by hand, trimming the destination tos.len. -
Add a test for each silent change you fix, so a later merge cannot undo it, and report anything left deprecated on purpose.
Merging an upgraded main into a 0.16 branch: merge, do not rebase. Take
main's side where a conflict differs only in 0.16 spellings; keep the branch's
behavior changes, written the 0.17 way. Then run steps 2 to 4 on the result.
Reviewing: run the scanner on the changed files, and treat a new
@hasDecl probe, containsAtLeastScalar call, or @bitCast of an array,
extern struct, or enum as a question. Rank memory safety, illegal behavior,
races, and leaks first, then contracts, then maintainability, then measured
speed or size. Correctness findings block; design alternatives are
considerations with their tradeoff.
Verification gate
Use the repository's commands first; otherwise run zig fmt --check on the
project's Zig paths, zig build, and zig build test with the pinned compiler.
Add only what the claim needs: a fuzz target when parsing or untrusted bytes
changed, Debug and ReleaseSafe when safety checks could matter, a cross-compile
for portability, ReleaseFast or ReleaseSmall for their speed or size, and the
built executable for runtime claims. Say what could not run.
References
Load one only when the task needs more than this file:
- types-memory-errors: data models, allocators, lifetimes, error sets, arithmetic, casts, generics, state machines.
- api-maintainability: public APIs, module boundaries, naming, documentation, refactors.
- io-concurrency-security:
std.Io, files, sockets, subprocesses, paths, threads, locks, atomics, external input. - testing-build-size: tests, fuzzing, build modes, dependencies, performance, binary size.
- language: 0.17 casts, builtins, comptime, reflection, and removed syntax, with before and after code.
- std: exact 0.17 signatures, allocators, containers, ZON, rare deprecations.
- build-system:
build.zig,build.zig.zon, packages, translate-c, editor tooling. - toolchain: installing a Zig next to another, CI, targets, OS minimums, what 0.17.1 fixed and still breaks, port gotchas.
- examples.zig: compile-checked snippets;
zig test references/examples.zigpasses on 0.17.0 and 0.17.1.