Pylance Fails to Resolve Import from venv; Python Extension Uses Global Python for Helper Scripts

[Lukemendels]

Type: Bug

Behaviour

Pylance consistently shows the error "Import "firebase_functions" could not be resolved" for the line import firebase_functions in a main.py file. This occurs when the processsermonaudio folder is opened as a single-root workspace in VS Code.

This happens despite the following conditions being met:

1. The project uses a virtual environment (.venv) located directly within the workspace root (processsermonaudio/.venv/), created with Python 3.13.3. functions-framework (which provides firebase_functions) is confirmed installed in this venv via pip list.
2. The VS Code Python interpreter is selected to point to this virtual environment (...\processsermonaudio\.venv\Scripts\python.exe), and this is reflected in the VS Code status bar and initial Python Output logs as the "Active interpreter."
3. The workspace setting python.defaultInterpreterPath in processsermonaudio/.vscode/settings.json is explicitly set to .\.venv\Scripts\python.exe.
4. User settings.json contains no conflicting Python path settings.

Key Observation & Hypothesis:
The Python Output panel logs consistently show that after the Python extension correctly identifies the venv's Python interpreter, it subsequently uses the global Python installation (C:/Users/<UserID>/AppData/Local/Programs/Python/Python313/python.exe) to execute some of its own internal helper scripts (e.g., printEnvVariables.py, printEnvVariablesToFile.py). This behavior was observed with Python extension versions ms-python.python-2025.6.1 and ms-python.python-2025.4.0, and with Pylance versions 2025.5.1 and 2025.4.1.

It's hypothesized that the Pylance error occurs because it relies on environment information gathered by these helper scripts. Since these scripts are run by the global Python, the information does not include the venv's site-packages, leading Pylance to incorrectly conclude firebase_functions is unavailable. The core issue seems to be why the Python extension defaults to global Python for these helper scripts despite a venv being configured.

This might be thematically related to broader interpreter context issues like those discussed in GitHub issue #23448 for the vscode-python repository (though that issue focuses on multi-root workspaces, and this report is for a single-root setup).

Troubleshooting Steps Attempted (without resolution for Pylance error):

• Confirmed functions-framework in requirements.txt and successful installation in venv.
• Ensured processsermonaudio folder is the workspace root.
• Explicitly selected venv interpreter; set python.defaultInterpreterPath in workspace settings.
• Confirmed User settings.json has no conflicting Python paths.
• Multiple VS Code reloads ("Developer: Reload Window", "Python: Clear Cache and Reload Window").
• Launched VS Code from an external PowerShell directly into the processsermonaudio directory.
• Verified workspace trust.
• Confirmed system PYTHONPATH and PYTHONHOME are unset/empty, and pyenv is not installed.
• Tested with multiple Python extension and Pylance versions (details should be auto-included by the reporter, but specifically Python Extension 2025.6.1 & 2025.4.0, Pylance 2025.5.1 & 2025.4.1).

Expected Behaviour:
Pylance should resolve imports from packages installed in the selected virtual environment. The Python extension should consistently use the selected virtual environment's Python interpreter for all its internal helper scripts related to environment discovery for that workspace.

Request:
Could you please investigate why the Python extension might use a global Python interpreter to run some of its internal helper scripts even when a virtual environment is properly selected and configured as the active interpreter for the workspace (in a single-root setup)?

Steps to reproduce:

1. Setup:
   • OS: Windows 11
   • Global Python: Python 3.13.3 installed at a path like C:\Users\<UserID>\AppData\Local\Programs\Python\Python313\python.exe.
   • VS Code with Python extension and Pylance installed.
2. Create Project Structure:
   • Create a folder for a Python project (e.g., C:\Users\<UserID>\Documents\Projects\SermonFlow\sermonflow-backend\functions\processsermonaudio).
3. Open in VS Code:
   • Open this processsermonaudio folder as a single-root workspace in VS Code.
4. Create and Activate Virtual Environment:
   • In the VS Code terminal, navigate to this folder.
   • Create a venv: python -m venv .venv (using the global Python 3.13.3).
   • Activate the venv: .\.venv\Scripts\Activate.ps1.
5. Install Dependencies:
   • Create requirements.txt in processsermonaudio with the content:

     firebase-admin
     functions-framework

   • In the activated venv terminal, run pip install -r requirements.txt. Verify functions-framework installs.
6. Configure VS Code Interpreter:
   • Use "Python: Select Interpreter" command to choose .\.venv\Scripts\python.exe from the current workspace.
   • Optionally, create .vscode/settings.json in processsermonaudio with:

     {
       "python.defaultInterpreterPath": "./.venv/Scripts/python.exe"
     }

   • Reload VS Code window.
7. Create Python File:
   • Create main.py in processsermonaudio with the content:

     import firebase_functions # Pylance error expected here
     print("firebase_functions imported?")

8. Observe Behaviour:
   • Pylance flags import firebase_functions with "Import "firebase_functions" could not be resolved".
   • Check the "Python" Output panel for logs showing the pattern of global Python usage for helper scripts.

Diagnostic data

Output for Python in the Output panel (View→Output, change the drop-down the upper-right of the Output panel to Python)

2025-05-21 06:02:04.256 [info] Experiment 'pythonRecommendTensorboardExt' is active
2025-05-21 06:02:04.257 [info] Experiment 'pythonTerminalEnvVarActivation' is active
2025-05-21 06:02:04.257 [info] Native locator: Refresh started
2025-05-21 06:02:04.257 [info] Native locator: Refresh started
2025-05-21 06:02:04.257 [info] > pyenv which python
2025-05-21 06:02:04.257 [info] cwd: .
2025-05-21 06:02:09.393 [info] Python interpreter path: .\.venv\Scripts\python.exe
2025-05-21 06:02:09.711 [info] Native locator: Refresh finished in 23678 ms
2025-05-21 06:02:17.661 [info] Starting Pylance language server.
2025-05-21 06:02:19.243 [info] > & ./.venv/Scripts/Activate.ps1 ; echo 'e8b39361-0157-4923-80e1-22d70d46dee6' ; python ~/.vscode/extensions/ms-python.python-2025.4.0-win32-x64/python_files/printEnvVariables.py
2025-05-21 06:02:19.245 [info] shell: powershell
2025-05-21 06:02:37.585 [info] > ~\AppData\Local\Programs\Python\Python313\python.exe ~/.vscode/extensions/ms-python.python-2025.4.0-win32-x64/python_files/printEnvVariables.py
2025-05-21 06:02:37.586 [info] shell: powershell
2025-05-21 06:03:00.286 [info] Prepending environment variable PATH in collection with c:\Users\<UserID>\.vscode\extensions\ms-python.python-2025.4.0-win32-x64\python_files\deactivate\powershell;C:\Users\<UserID>\Documents\Projects\SermonFlow\sermonflow-backend\Functions\processSermonAudio\.venv\Scripts; {"applyAtShellIntegration":true,"applyAtProcessCreation":true}
2025-05-21 06:03:00.287 [info] Setting environment variable VIRTUAL_ENV in collection to C:\Users\<UserID>\Documents\Projects\SermonFlow\sermonflow-backend\Functions\processSermonAudio\.venv {"applyAtShellIntegration":true,"applyAtProcessCreation":true}
2025-05-21 06:03:00.287 [info] Setting environment variable VIRTUAL_ENV_PROMPT in collection to .venv {"applyAtShellIntegration":true,"applyAtProcessCreation":true}
2025-05-21 06:03:00.295 [info] Send text to terminal: & C:/Users/<UserID>/AppData/Local\Programs\Python\Python313\python.exe c:\Users\<UserID>\.vscode\extensions\ms-python.python-2025.4.0-win32-x64\python_files\printEnvVariablesToFile.py c:\Users\<UserID>\.vscode\extensions\ms-python.python-2025.4.0-win32-x64\python_files\deactivate\powershell\envVars.txt

Extension version: 2025.4.0
VS Code version: Code 1.100.2 (848b80aeb52026648a8ff9f7c45a9b0a80641e2e, 2025-05-14T21:47:40.416Z)
OS version: Windows_NT x64 10.0.26100
Modes:

• Python version (& distribution if applicable, e.g. Anaconda): 3.13.3
• Type of virtual environment used (e.g. conda, venv, virtualenv, etc.): Venv
• Value of the python.languageServer setting: Default

User Settings

languageServer: "Pylance"

Installed Extensions

Extension Name	Extension Id	Version
azure-repos	ms-	0.40.0
cloudcode	goo	2.30.0
copilot	Git	1.322.0
copilot-chat	Git	0.27.1
debugpy	ms-	2025.4.1
docker	doc	0.6.0
geminicodeassist	goo	2.33.0
gitlens	eam	17.1.0
js-debug	ms-	1.100.1
js-debug-companion	ms-	1.1.3
LiveServer	rit	5.7.9
prettier-vscode	esb	11.0.0
python	ms-	2025.4.0
remote-containers	ms-	0.413.0
remote-repositories	ms-	0.42.0
remotehub	Git	0.64.0
vscode-docker	ms-	1.29.6
vscode-js-profile-table	ms-	1.0.10
vscode-pylance	ms-	2025.4.1

System Info

Item	Value
CPUs	Intel(R) Pentium(R) Silver N5030 CPU @ 1.10GHz (4 x 1094)
GPU Status	2d_canvas: enabled canvas_oop_rasterization: enabled_on direct_rendering_display_compositor: disabled_off_ok gpu_compositing: enabled multiple_raster_threads: enabled_on opengl: enabled_on rasterization: enabled raw_draw: disabled_off_ok skia_graphite: disabled_off video_decode: enabled video_encode: enabled vulkan: disabled_off webgl: enabled webgl2: enabled webgpu: enabled webnn: disabled_off
Load (avg)	undefined
Memory (System)	3.83GB (0.47GB free)
Process Argv	. --crash-reporter-id 579effca-e82b-405e-b7df-54752692650d
Screen Reader	no
VM	0%

A/B Experiments

vsliv368:30146709
vspor879:30202332
vspor708:30202333
vspor363:30204092
vscod805cf:30301675
binariesv615:30325510
c4g48928:30535728
azure-dev_surveyone:30548225
2i9eh265:30646982
962ge761:30959799
h48ei257:31000450
pythontbext0:30879054
cppperfnew:31000557
dwnewjupyter:31046869
pythonrstrctxt:31112756
nativeloc1:31192215
5fd0e150:31155592
dwcopilot:31170013
6074i472:31201624
dwoutputs:31242946
customenabled:31248079
hdaa2157:31222309
copilot_t_ci:31222730
e5gg6876:31282496
pythoneinst12:31285622
bgtreat:31268568
4gafe986:31271826
c7cif404:31309971
pythonpulldiagcf:31298646
996jf627:31283433
pythonrdcb7:31303018
usemplatestapi:31297334
0aa6g176:31307128
7bj51361:31289155
747dc170:31275177
pylancecolorcf:31309109
aj953862:31281341
generatesymbolt:31295002
convertfstringf:31295003
gendocf:31295004
j6a0c355:31309728

[Lukemendels]

Following up on this:

The Pylance "import not resolved" error has now been resolved locally on my system. The resolution occurred after I took steps to prepare for deploying the Python Cloud Function using the Firebase CLI, which involved creating a new virtual environment in a standard functions directory.

Here's a summary of the steps that led to the fix:

1. Previously, I was working with a main.py file and a virtual environment (.venv) located within a specific subdirectory: C:\Users\<UserID>\Documents\Projects\SermonFlow\sermonflow-backend\functions\processSermonAudio\. Pylance was consistently failing to resolve import firebase_functions in this setup. The Python Output logs (as previously submitted with the original report) showed the Python extension sometimes using my global Python for helper scripts.

2. To prepare for Firebase deployment, I navigated to the parent directory C:\Users\<UserID>\Documents\Projects\SermonFlow\sermonflow-backend\ and ran firebase init functions.

   • This command created a new subdirectory functions\ (i.e., C:\Users\<UserID>\Documents\Projects\SermonFlow\sermonflow-backend\functions\) and also set up a new virtual environment within it (C:\Users\<UserID>\Documents\Projects\SermonFlow\sermonflow-backend\functions\.venv\).
   • An initial pip self-upgrade error occurred during the firebase init functions process's automated dependency installation step.

3. I then manually:

   • Activated the new virtual environment located at C:\Users\<UserID>\Documents\Projects\SermonFlow\sermonflow-backend\functions\.venv\.
   • Successfully upgraded pip within this new venv using python.exe -m pip install --upgrade pip.
   • Ensured the main.py file (containing import firebase_functions and the say_hello function) was now located at C:\Users\<UserID>\Documents\Projects\SermonFlow\sermonflow-backend\functions\main.py.
   • Ensured the requirements.txt file in C:\Users\<UserID>\Documents\Projects\SermonFlow\sermonflow-backend\functions\ correctly listed firebase-admin and functions-framework.
   • Ran pip install -r requirements.txt while this new venv was active and I was in the ...\sermonflow-backend\functions\ directory.

4. Outcome: After these steps, I opened C:\Users\<UserID>\Documents\Projects\SermonFlow\sermonflow-backend\functions\main.py in VS Code. With the interpreter from C:\Users\<UserID>\Documents\Projects\SermonFlow\sermonflow-backend\functions\.venv\ selected, Pylance no longer shows the "Import firebase_functions could not be resolved" error.
   Interestingly, the error also seems to have resolved in my original ...\functions\processSermonAudio\main.py file as well, suggesting a broader positive effect on how VS Code/Pylance is now understanding the Python environments in this workspace.

Possible Implications for the Original Bug:
It seems that the process of firebase init functions creating a new virtual environment in a more standard/expected location (functions/.venv/ relative to where Firebase tools might be looking or where firebase.json is configured for functions), and then explicitly setting up that environment, allowed the VS Code Python extension and Pylance to correctly recognize the installed packages.

This might suggest that the original issue could be related to:

• How the Python extension discovers/validates venvs in more nested subdirectories if they are not the primary "functions source" directory configured in firebase.json.
• A caching issue in Pylance/Python extension that was cleared by focusing on this newly created and configured venv.
• The specific way the initial venv in the processSermonAudio subdirectory was created or selected might have led to the inconsistent behavior noted in the Python Output logs. The fresh venv created by firebase init functions might have avoided this.

While my specific local issue is now resolved through this workaround, the underlying behavior noted in the original Python Output logs (where the extension used global Python for helper scripts despite a venv being selected) might still be worth investigating to improve robustness for other users or different project structures.