Dict iteration order differs between Python 3.6 and 3.7+ — what should code rely on?

Short answer

If your minimum supported version is 3.6, do not rely on plain dict ordering as a contract — but you also don't need a version branch. Use collections.OrderedDict (or explicitly sort keys) at the point where order affects output, and plain dict everywhere else. On 3.7+ you can rely on dict insertion order unconditionally.

What is guaranteed, and what is an implementation detail

The confirmed facts, separated from the surrounding folklore:

• Python 3.7+: insertion-order preservation for the built-in dict is part of the language specification. Every compliant implementation must honor it. Code targeting 3.7+ can rely on it fully.
• CPython 3.6: the compact-dict implementation happens to preserve insertion order, and in practice CPython 3.6 behaves identically to 3.7+. But it is documented as an implementation detail, not a language guarantee. Alternative implementations of 3.6 (PyPy3.6-era builds, embedded interpreters) were not bound by it.

So the practical risk on 3.6 is not CPython itself — it is claiming a guarantee the language doesn't make, and any non-CPython 3.6 runtime your users might deploy on.

Do you need a sys.version_info branch?

No. Branching adds a second code path to maintain and test, and it buys nothing: OrderedDict works correctly on 3.7+ too (it is now a thin wrapper with a few extra features like move_to_end and order-sensitive equality). The portable pattern is to make ordering explicit only where it matters:

from collections import OrderedDict

def build_query(params):
    # params may be any mapping; normalize at the boundary
    ordered = OrderedDict(params)  # or: sorted(params.items())
    return "&".join(f"{k}={v}" for k, v in ordered.items())

If the caller controls key order and you just need a deterministic order (e.g., config files, cache keys), sorting keys is often simpler and removes the dependency on how the mapping was constructed at all.

C extensions and mapping-like objects

The 3.7+ guarantee applies to the built-in dict type, not to the abstract concept of mappings. A C extension returning a custom mapping type defines its own iteration semantics. Even on 3.7+, such an object may iterate in hash order, sorted order, or arbitrary order. Two implications:

• Treat any mapping that isn't literally a dict (or OrderedDict) as unordered unless its documentation says otherwise.
• Normalize at your library's boundary — OrderedDict(mapping.items()) or sorted(mapping.items()) — so extension-provided mappings can't leak nondeterminism into your serialized output.

Testing deterministically across versions

1. Build the mapping through your normalization layer (OrderedDict or sorted keys), never by relying on raw dict iteration.
2. Assert on the exact serialized string, not on dict equality — two dicts with the same items in different insertion order compare equal, so assert d1 == d2 will not catch ordering bugs.
3. Run the test suite under both a 3.6 and a 3.7+ interpreter (tox or CI matrix). A minimal tox config:

[tox]
envlist = py36, py311
[testenv]
commands = pytest tests/test_serialization.py

If you consume extension-provided mappings, add one test with a deliberately scrambled mapping (a stub object whose items() yields keys in reverse) to prove your normalization actually enforces order rather than inheriting it by luck.

Recommendation

Keep plain dict for internal storage, normalize to OrderedDict or sorted items at serialization boundaries, and assert on serialized bytes/strings in a two-version CI matrix. That gives you deterministic output on 3.6 and 3.7+ with a single code path and no version sniffing. If you can drop 3.6 support (it is long past end-of-life), the normalization can shrink to plain dict — but keep the boundary normalization for third-party mapping objects regardless.