docs: Document Flash local (non-pip) module bundling for endpoints - #775
Conversation
Documents runpod/flash PR #352: automatic bundling of local Python modules that endpoints import. Adds an 'Import local modules' section to create-endpoints (supported import forms, transitive resolution, 8 MiB live cap, parent-directory constraint), a force-include note to the build CLI reference, and troubleshooting entries for the new resolution and payload-size errors.
…l-module-bundling
Rewrite the build page's local-module section to match merged behavior (the build validates against the ignore filter and fails loudly on ignore-excluded or unresolvable endpoint imports; it does not force-include ignored files), clarify transitive pip dependencies, add the ignore-excluded LocalModuleResolutionError variant to troubleshooting, and tighten cross-links. Ref: runpod/flash#352 (SLS-360)
…l-module-bundling # Conflicts: # release-notes.mdx
![promptless[bot]](https://avatars.githubusercontent.com/in/979718?s=60&v=4){kind=small}
| return {"processed": True} | ||
| ``` | ||
|
|
||
| ## Import local modules |
There was a problem hiding this comment.
Documents the local-module bundling feature added in PR #352. stubs/local_modules.py::resolve_local_modules walks the transitive local-import closure (absolute, relative, and literal importlib.import_module imports, at module level and in function bodies), pulls in package __init__.py files, classifies stdlib/installed names as external, and warns on non-literal dynamic imports; stubs/live_serverless.py::build_modules_map ships the resolved source inline via the new FunctionRequest.modules field and enforces MAX_INLINE_MODULE_BYTES = 8 MiB.
Source: runpod/flash#352
|
|
||
| When you run an endpoint live (calling an `@Endpoint` function directly, or during `flash dev`), Flash ships the resolved module source inline with the request. The combined source is capped at 8 MiB. If your local dependencies exceed this limit, deploy the app with `flash deploy` instead, which bundles local modules into the build artifact rather than the request payload. See [Local module payload too large](/flash/troubleshooting#local-module-payload-too-large) for the corresponding error. | ||
|
|
||
| ### Local modules in a parent directory |
There was a problem hiding this comment.
Documents the parent-directory constraint. The docstring note in stubs/local_modules.py::resolve_local_modules states that on the live path a module imported by absolute name from a parent directory is classified as external and silently omitted (raising ModuleNotFoundError on the worker); only relative imports fail loudly, and the workaround is to keep the endpoint at/above its local deps or use flash deploy.
Source: runpod/flash#352
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
| If you use other environment file variants like `.env.dev` or `.env.staging`, add them to your `.gitignore` to exclude them from deployment artifacts. | ||
| </Tip> | ||
|
|
||
| ### Local modules and the ignore filter |
There was a problem hiding this comment.
Documents the build-path validation behavior (merged PR #352, not force-include). validate_local_module_imports in cli/commands/build.py is called from run_build AFTER files = get_file_tree(project_dir, spec) (the ignore-filtered shipped set) is computed; it never expands that set. For every shipped .py file it walks the local-import closure via stubs/local_modules.py::resolve_local_modules and checks each resolved file against the already-ignore-filtered files. If a shipped file imports a local module the ignore rules excluded, the build is refused (LocalModuleResolutionError -> typer.Exit(1)) with an actionable message naming the excluded file and its importer — it does NOT force-include the file. Strictness for unresolvable imports is scoped to endpoint files via build_utils/scanner.py::defines_endpoint (recognizing @remote/@Endpoint): an endpoint file with an unresolvable local import fails the build loudly, while a non-endpoint file that fails resolution is skipped with a warning and the build continues.
Source: runpod/flash#352
There was a problem hiding this comment.
(Line 488)
Documents the LocalModulePayloadTooLargeError raised in stubs/live_serverless.py::build_modules_map when the inline module payload exceeds MAX_INLINE_MODULE_BYTES (8 * 1024 * 1024 = 8388608 bytes = 8 MiB), defined in stubs/local_modules.py. The raised message is a single continuous string: "Inline module payload is {total} bytes, over the {MAX_INLINE_MODULE_BYTES}-byte live-serverless cap. Use flash deploy for endpoints with large local dependencies." — no embedded newline; the docs code block wraps it onto two lines for readability. The error points users to flash deploy, which is the documented solution. Anchor moved from line 484 (inside the unrelated pre-existing "Payload too large" section) to line 488, the heading of the new "Local module payload too large" section this citation actually supports.
Source: runpod/flash#352
|
|
||
| **July 28, 2026** | ||
|
|
||
| <h4><Badge color="green">New Release</Badge> [Automatic local module bundling for Flash endpoints](/flash/create-endpoints#import-local-modules) </h4> Flash now automatically bundles the local Python modules your endpoints import — sibling files and packages that aren't installed via pip — and ships their source to the worker. Imports like `import utils` or `from helpers import x` now work remotely with no extra configuration. |
There was a problem hiding this comment.
Announces the local (non-pip) module bundling feature implemented in PR #352 (merged 2026-07-20): stubs/local_modules.py::resolve_local_modules resolves the transitive local-import closure and stubs/live_serverless.py::build_modules_map ships the resolved source inline to the worker via the new FunctionRequest.modules field, so imports like import utils or from helpers import x work remotely with no extra configuration. The July 28, 2026 entry date matches the merge date of release PR #356 ("chore: release 1.19.0"), the release that shipped PR #352. Full technical detail (parent-directory constraint, 8 MiB inline cap, build-time validation) is already covered by the existing citations on flash/create-endpoints.mdx, flash/cli/build.mdx, and flash/troubleshooting.mdx; this citation anchors the release-announcement entry itself.
Source: runpod/flash#352
|
@Promptless: can you remove the hyphens added in between the texts from the draft? |
|
Thanks — on it. I'll remove the stray hyphens inserted between words in the draft and push an update to this PR shortly. |
|
Update: I found two stray dash connectors in the prose (one in the release notes entry and one in a link label on the create-endpoints page) and I'm removing those. Legitimate compound terms like "non-pip" and "built-in", along with error messages and code, are left untouched. Pushing the change shortly. |
Address PR review feedback (#775): replace the em-dash parenthetical connector in the July 28 release-notes entry with parentheses, and drop the 'flash build - ' connector prefix from the create-endpoints link text. Preserves compound modifiers, error-message strings, and code identifiers.
|
Done — I removed the two dash connectors that had been inserted between words in the draft:
I left legitimate hyphenation in place — compound terms like |
|
@Promptless remove the release notes entry for this update |
|
On it — I'll remove the release notes entry for this update from this PR and push the change here shortly. |
|
Scoped the change: I'll remove the July 28, 2026 "Product updates" entry from the release notes. Nothing else links to it, so the other pages in this PR (create-endpoints, build CLI reference, troubleshooting) stay as-is. Making the edit now. |
Address PR review feedback (#775): remove the July 28, 2026 Product updates entry announcing Flash automatic local module bundling, per @lavanya-gunreddi's request. The create-endpoints, build CLI reference, and troubleshooting content remain in the suggestion.
|
Done — the release notes entry has been removed and the change is pushed to this PR. The other pages are unchanged. |
|
Done — the release notes (Product updates) entry for this update has been removed from this PR. The rest of the documentation stays in place: the "Import local modules" section on the create-endpoints page, the build CLI reference behavior, and the troubleshooting entries are all unchanged. |
1 participant
Open in Promptless
Documents Flash's new first-class support for bundling local (non-pip) Python modules that endpoints import (runpod/flash PR #352, SLS-360), shipped in Flash v1.19.0 (release PR #356, merged 2026-07-28). Adds an "Import local modules" section to create-endpoints (supported import forms, transitive resolution, transitive pip-dependency note, the 8 MiB live-path cap, and the parent-directory absolute-import constraint), documents the build behavior on the build CLI reference (local modules are bundled when they pass the ignore filter; the build fails with a LocalModuleResolutionError on ignore-excluded or unresolvable endpoint imports rather than force-including files), and adds two troubleshooting entries for the resolution error (both variants) and the payload-too-large error. Note: the build path validates against the ignore filter and refuses — it does not force-include ignore-excluded files, correcting the PR body's stale "force-include" wording against the merged code.
Trigger Events
Review feedback addressed
Applied @lavanya-gunreddi's request to remove the release notes entry for this update:
release-notes.mdx: applied verbatim — removed the July 28, 2026 "Product updates" entry that announced Flash automatic local module bundling. The entry's outbound link target (the create-endpoints "Import local modules" section) is retained, and no other page linked into the removed entry, so no cross-links were broken.The create-endpoints "Import local modules" section, the build CLI reference behavior, and the troubleshooting entries remain unchanged.
Earlier review pass (@lavanya-gunreddi): removed two draft-introduced dash connectors — the em-dash parenthetical pair in the (now-removed) release-notes entry and the "
flash build- " connector prefix in the create-endpoints link text. Legitimate hyphenation (compound modifiers likenon-pip,built-in,ignore-excluded; verbatim error-message strings; and code identifiers) was preserved.Tip: Worried about broken links? Ask Promptless to find and fix them automatically 🔗