Lua module reload recovery via package.loaded invalidation

Answer

No. Clearing package.loaded[modname] removes the cached entry, but it does not update references already captured by other modules. Dependents that stored the old table in a local, upvalue, or field will continue using that table unless they re-require the module or explicitly replace the reference.

Confirmed behavior

• require returns the value stored in package.loaded[modname] when that entry is present and non-nil.
• Deleting the entry forces the next require to run the searcher and execute the loader again.
• Existing references held by other modules are unaffected by the deletion.
• In Lua 5.1, a loader that returns nil causes require to store true and return true; in Lua 5.2 and later, returning nil from a loader raises an error.

Conditions for a matching reload

1. The module file must be present, readable, and compile without syntax or load errors.
2. The searcher must resolve modname to the same loader function on each call; otherwise the reloaded module may come from a different source.
3. The loader must be idempotent: running it again must produce a table equivalent to the pre-upgrade implementation without duplicating side effects.
4. Any internal caches inside the module (for example, lazy-loaded submodules) must be invalidated or rebuilt during the reload.

Version-specific risks

• Lua 5.1: A loader returning nil silently yields true, which can mask a partially initialized module.
• Lua 5.2+: The loader must return a non-nil value; a failed upgrade that leaves the loader returning nil will raise an error instead of caching a broken table.
• LuaJIT: Bytecode and JIT compilation can make reload semantics less predictable. Verify that the reloaded chunk executes the updated source rather than a stale compiled artifact; this point requires confirmation against your specific LuaJIT version.

Verification steps

1. After clearing the entry, confirm package.loaded[modname] == nil.
2. Re-require the module and check that the returned table is not identical (~=) to the old reference held by a dependent.
3. Run a smoke test that exercises the module’s public interface to ensure the reloaded implementation matches expectations.

Missing diagnostic: Do any dependent modules hold a direct reference to the old module table (for example, a local variable or a cached field)? If they do, clearing package.loaded alone will not refresh them, and the recovery must include re-binding those references.