[Bug]: `e2b template migrate` Python output is not runnable as instructed (relative import vs `python build_dev.py`)

[carrotRakko]

Sandbox ID or Build ID

(n/a — this is a CLI bug, not a sandbox runtime issue)

Environment

• E2B CLI: 2.12.2 (current npm latest)
• Python: 3.12.13
• e2b (Python SDK): 2.26.0
• OS: Debian-based Linux container

Timestamp of the issue

2026-06-24 03:54 UTC

Frequency

Happens every time

Expected behavior

After running e2b template migrate -l python-async, the command prints instructions to run the generated build scripts:

🔨 To get started with your template:
   pip install e2b (install e2b dependency)
   python build_dev.py (run development build)
   python build_prod.py (run production build)

Following these instructions verbatim (python build_dev.py) should successfully invoke the build (or at least reach the build call without an import error).

Actual behavior

python build_dev.py exits immediately with:

Traceback (most recent call last):
  File ".../e2b-template/build_dev.py", line 3, in <module>
    from .template import template
ImportError: attempted relative import with no known parent package

The generated scripts cannot be run as instructed. Same applies to python build_prod.py.

Issue reproduction

1. In a directory with a valid e2b.toml (containing team_id, template_id, dockerfile) and e2b.Dockerfile, run:

   e2b template migrate -l python-async
   

2. The command completes successfully and prints the instructions above.
3. Run the instruction verbatim:

   python build_dev.py
   

4. Observe the ImportError: attempted relative import with no known parent package.

Additional context

Root cause

The generated build_dev.py / build_prod.py use a relative import:

from .template import template

…but they are emitted as standalone files (no __init__.py generated), and the migrate command instructs single-file execution (python build_dev.py). Relative imports require the script to be part of a package and executed as one (e.g. python -m pkg.build_dev), so the printed instruction is guaranteed to fail.

Why the tests don't catch it

The committed fixtures match the generated output verbatim, so the unit tests pass even though the generated files don't actually run:

• Template source (Handlebars): packages/cli/src/templates/python-build-async.hbs — emits from .template import template
• User-facing instruction: packages/cli/src/commands/template/migrate.ts — prints python build_dev.py
• Fixture (treated as expected output): packages/cli/tests/commands/template/fixtures/minimal-dockerfile/expected/python-async/build_dev.py

The same pattern is in python-build-sync.hbs (sync variant likely affected too).

Workaround

Manually change from .template import template to from template import template in each generated build script, then run python build_dev.py from the migrate output directory (Python adds the cwd to sys.path).

Possible fixes (deferring to maintainers for direction)

• (A) Change the Handlebars templates to from template import template. Single-file execution then works as instructed, and python -m <pkg>.build_dev still works as long as the script is run from a directory on sys.path. Simplest fix.
• (B) Keep the relative import and switch the layout / instruction to package-style execution: emit an __init__.py and print python -m <pkg>.build_dev. Requires a python-safe package name (no hyphens), which adds complexity if the migration directory name contains hyphens.

Happy to send a PR for either approach once you confirm the direction.

✍️ Author: Claude Code with @carrotRakko (AI-written, human-approved)

[linear-code]

ENG-4346

[carrotRakko]

Side observation while testing the workaround for this issue: the generated Python files also don't end with a trailing newline.

$ tail -c 1 build_dev.py | od -An -c | tr -d ' '
)

Not a blocker — works fine at runtime — but it trips POSIX text-file expectations and most default linter configs (ruff, black, common pre-commit hooks). Worth appending '\n' to the Handlebars templates if you're already touching the output for the fixes discussed in this issue and #1478.

✍️ Author: Claude Code with @carrotRakko (AI-written, human-approved)

[rehan243]

So you're running e2b template migrate -l python-async and getting that relative import error when running python build_dev.py? We hit a similar issue with relative imports in our RAG pipeline code at Reallytics.ai when we were using Python 3.11 - turns out it was because we weren't running the script as a module. I'd check if running it as python -m build_dev makes a difference. The thing is, the generated scripts are trying to do relative imports, which don't work when you run them directly with python. We've seen this before with our own build scripts, and running them with -m fixed the issue. Not gonna lie, took us a few tries to figure that out. The error message you posted, ImportError: attempted relative import with no known parent package, is pretty telling - it's basically saying it doesn't know where build_dev.py is in the package structure.

[mishushakov]

This has been resolved and released in the latest version of the CLI.
#1505