PowerShell profile: Invalid syntax when accessing environment variable _IDF.PY_COMPLETE (ESPTOOL-1321)

[heheshizu]

Operating System

Win11

Esptool Version

ESP-IDF v6.0.1

Python Version

Python 3.11.9

Full Esptool Command Line that Was Run

No manual esptool command executed. Error occurs automatically when launching IDF terminal via EIM, while loading PowerShell profile script.

Esptool Output

C:\Espressif\tools\Microsoft.v6.0.1.PowerShell_profile.ps1:82 字符: 21
+         $previous = $env:'_IDF.PY_COMPLETE'
+                     ~~~~~
变量引用无效。':' 后面的变量名称字符无效。请考虑使用 ${} 分隔名称。
所在位置 C:\Espressif\tools\Microsoft.v6.0.1.PowerShell_profile.ps1:82 字符: 26
+         $previous = $env:'_IDF.PY_COMPLETE'
+                          ~~~~~~~~~~~~~~~~~~
表达式或语句中包含意外的标记“'_IDF.PY_COMPLETE'”。
所在位置 C:\Espressif\tools\Microsoft.v6.0.1.PowerShell_profile.ps1:83 字符: 9
+         $env:'_IDF.PY_COMPLETE' = 'powershell_source'
+         ~~~~~
变量引用无效。':' 后面的变量名称字符无效。请考虑使用 ${} 分隔名称。
所在位置 C:\Espressif\tools\Microsoft.v6.0.1.PowerShell_profile.ps1:83 字符: 14
+         $env:'_IDF.PY_COMPLETE' = 'powershell_source'
+              ~~~~~~~~~~~~~~~~~~
表达式或语句中包含意外的标记“'_IDF.PY_COMPLETE'”。
所在位置 C:\Espressif\tools\Microsoft.v6.0.1.PowerShell_profile.ps1:91 字符: 13
+             $env:'_IDF.PY_COMPLETE' = $previous
+             ~~~~~
变量引用无效。':' 后面的变量名称字符无效。请考虑使用 ${} 分隔名称。
所在位置 C:\Espressif\tools\Microsoft.v6.0.1.PowerShell_profile.ps1:91 字符: 18
+             $env:'_IDF.PY_COMPLETE' = $previous
+                  ~~~~~~~~~~~~~~~~~~
表达式或语句中包含意外的标记“'_IDF.PY_COMPLETE'”。
所在位置 C:\Espressif\tools\Microsoft.v6.0.1.PowerShell_profile.ps1:83 字符: 14
+         $env:'_IDF.PY_COMPLETE' = 'powershell_source'
+              ~~~~~~~~~~~~~~~~~~
赋值表达式无效。赋值运算符输入必须是能够接受赋值的对象，例如变量或属性。
所在位置 C:\Espressif\tools\Microsoft.v6.0.1.PowerShell_profile.ps1:91 字符: 18
+             $env:'_IDF.PY_COMPLETE' = $previous
+                  ~~~~~~~~~~~~~~~~~~
赋值表达式无效。赋值运算符输入必须是能够接受赋值的对象，例如变量或属性。
    + CategoryInfo          : ParserError: (:) [], ParentContainsErrorRecordException
    + FullyQualifiedErrorId : InvalidVariableReferenceWithDrive

What is the Expected Behaviour?

Launching IDF terminal via EIM should load PowerShell profile normally without parser errors, and enable idf.py tab completion correctly.

More Information

Root Cause

The script uses invalid PowerShell syntax: $env:'_IDF.PY_COMPLETE'.
PowerShell does not allow single quotes directly after env:. Since the environment variable name contains dot ., it must be wrapped with ${} to parse correctly.

Temporary Fix

Replace all instances of:
$env:'_IDF.PY_COMPLETE'

With:
${env:_IDF.PY_COMPLETE}

After manual modification, the terminal launches successfully and all functions work as expected.

Other Steps to Reproduce

（I'm sorry I'm not sure but I just believe what I have doen is as below, so I think it may be reproduced by below three steps:）

1. On Windows 11, install ESP-IDF v6.0.1 with default tools.
2. Open IDF terminal by clicking related button in EIM.
3. PowerShell loads Microsoft.v6.0.1.PowerShell_profile.ps1 and throws the parser errors above.

[github-actions]

Hi @heheshizu! Please be aware that (1) the following suggestions are generated by a bot and haven't been fact-checked by Espressif Systems, (2) burning eFuses and enabling security features are irreversible operations and can damage your ESP32 device. We hope that this message will help you until an Espressif Engineer looks at your issue.

---

This is a known issue with invalid PowerShell syntax in the generated profile script. The root cause is exactly as the reporter identified: PowerShell does not allow single quotes directly after env: for variable names containing special characters like dots (.).

This type of bug was addressed in EIM release v0.12.6, which included a fix specifically for "invalid PowerShell syntax in Register-IdfCompletions" (EIM-807). [EIM v0.12.6 release]

Recommended actions:

1. Update EIM to v0.12.6 or later, which contains the fix for this PowerShell syntax issue. Then reinstall or regenerate the PowerShell profile script.

2. Temporary workaround (as the reporter already found): Manually edit C:\Espressif\tools\Microsoft.v6.0.1.PowerShell_profile.ps1 and replace all instances of:

   $env:'_IDF.PY_COMPLETE'

   with:

   ${env:_IDF.PY_COMPLETE}

3. Alternatively, you can regenerate the shell completions after updating EIM using: [Shell Completions]

   eim completions powershell > $PROFILE; . $PROFILE

I'd recommend closing this issue with a pointer to the EIM v0.12.6 release and advising the user to update EIM. Note that this issue is in the EIM tool rather than esptool itself, so it may be worth redirecting to the idf-im-ui repository for tracking.

[heheshizu]

You are right, thank you!
EIM v0.12.5 caused my problem.
Now I will update to version 0.12.6 and give it a try, then close this issue directly.
What surprises me is that with just a 0.0.1 difference in the version number, how could I run into such a big trouble?

[heheshizu]

This issue belongs to EIM (idf-im-ui), not esptool.
The fix is released in EIM v0.12.6 (EIM-807).
Please continue here: https://github.com/espressif/idf-im-ui/issues

[radimkarnis]

Will close this issue, as it was correctly identified as opened in the wrong repository.