Fix Unresolved Imports in PyCharm After Switching Virtual Environments

Recognizable Condition

You create a new virtual environment or switch to an existing one in PyCharm. The editor immediately flags imports with red squiggles—unresolved reference warnings—even though pip list shows the packages installed. Running the script from the terminal works, but executing it via PyCharm's Run button throws ModuleNotFoundError. Code completion for those packages is also missing.

Cause and Diagnostic Table

Symptom	Possible Cause	Quick Check
Unresolved import warnings (red squiggles) in editor	Project interpreter still points to the old environment	File → Settings → Project → Python Interpreter — verify the path matches the new venv's python.exe (Windows) or python (Linux/macOS)
ModuleNotFoundError when running via Run/Debug configuration	Run configuration uses a different interpreter than the project setting	Run → Edit Configurations → Configuration → Interpreter — confirm it matches the project interpreter
No error but code completion missing; status bar shows "Indexing..." for >5 minutes	PyCharm hasn't finished indexing the new environment's site-packages	Bottom-right status bar — wait for "Indexes updated" or force re-index
Imports resolve in editor but fail at runtime (or vice versa)	Conflicting PYTHONPATH or multiple .idea workspace files	Check Run → Edit Configurations → Environment variables and inspect .idea/workspace.xml for duplicate entries

Ordered Diagnostic Checks

1. Verify the project interpreter. Open File → Settings → Project → Python Interpreter (Windows/Linux) or PyCharm → Preferences → Project → Python Interpreter (macOS). The displayed path must be the python executable inside the new venv (e.g., /home/user/project/venv/bin/python or C:\project\venv\Scripts\python.exe). If it shows a different path, click the gear icon → Add Interpreter → Existing Environment and select the correct executable.
2. Confirm packages exist in the venv. Open the built-in terminal (Alt+F12) — it should activate the venv automatically. Run pip list and verify the missing package appears. If not, install it: pip install package-name.
3. Check Run/Debug configuration interpreter. Go to Run → Edit Configurations. For each configuration, ensure Interpreter matches the project interpreter. PyCharm creates a default configuration per script; if you duplicated or edited one, it may retain the old interpreter.
4. Force re-indexing. If the interpreter is correct but squiggles persist, select File → Invalidate Caches… → check Clear file system cache and Local History → Invalidate and Restart. PyCharm will rebuild indexes for the venv's site-packages.
5. Remote SSH interpreters only: Verify the remote Python version matches the local project (python --version on the remote host). In Settings → Project → Python Interpreter, click the gear → Show All → select the SSH interpreter → Path Mappings and ensure local project root maps to the correct remote directory. Then click Sync to resync the remote package list.

Fixes Tied to Findings

Wrong Interpreter Path

Select the correct venv executable in Project Interpreter settings. PyCharm triggers an automatic re-index; watch the status bar for "Indexes updated." If it stalls, proceed to step 4.

Outdated Run/Debug Configuration

Edit each affected configuration: Run → Edit Configurations → [your config] → Interpreter → choose the project interpreter (shows as "Project Default") or explicitly select the venv. Apply and re-run.

Missing Packages in the Venv

In the PyCharm terminal (which activates the venv), run:

pip install -r requirements.txt
# or
pip install specific-package==1.2.3

After installation, wait for indexing or trigger File → Invalidate Caches.

Stalled Indexing

If the status bar shows "Indexing..." for more than five minutes, invalidate caches as described in step 4. This clears the stale index and forces a fresh scan of site-packages.

Remote SSH Interpreter Issues

1. Confirm the remote host's Python version matches the project's python --version.
2. In the interpreter settings, use Sync to download the remote package skeletons.
3. If packages are missing on the remote host, install them via the remote terminal or add them to the deployment script.
4. Verify path mappings: local project root ↔ remote project root. Incorrect mappings cause PyCharm to look in the wrong remote directory for packages.

Concrete Example: Switching from Conda to Venv

A project originally used a Conda environment at /opt/conda/envs/myproj/bin/python. You create a standard venv at ./venv and install dependencies via pip install -r requirements.txt. After changing the project interpreter to ./venv/bin/python, the editor still shows unresolved imports for numpy and pandas.

Diagnosis: Run/Debug configuration still references the Conda interpreter. Fix: Edit the configuration, set Interpreter to "Project Default" (now the venv). Run again — ModuleNotFoundError disappears. If squiggles remain, invalidate caches.

Escalation Criteria

If imports remain unresolved after completing all five checks:

• Inspect .idea/workspace.xml for duplicate projectRoots or stale sdk entries. Do not edit this file manually — instead, close PyCharm, delete the .idea folder, and re-import the project (File → Open). PyCharm regenerates clean settings.
• Check for a PYTHONPATH environment variable set at the system, user, or Run Configuration level that points to an old site-packages directory. Remove or correct it.
• If using Poetry or Conda to manage the environment, ensure PyCharm points to the environment's actual python executable, not a wrapper script (e.g., poetry run python or conda run -n env python). Wrapper scripts cause intermittent resolution failures.
• Collect idea.log (Help → Show Log in Files) and contact JetBrains Support with the log, a minimal reproduction project, and the exact PyCharm version (Help → About).

Verification Steps

1. Open a Python file that previously showed red squiggles. The warnings should disappear; hover over an import to see the resolved package definition tooltip.
2. Run the script via the corrected Run/Debug configuration. It should execute without ModuleNotFoundError and produce the expected output.
3. Check the Event Log (bottom-right) for "Indexes updated" after invalidating caches, confirming PyCharm re-indexed the venv's site-packages.

Limitations

• This guide covers PyCharm 2023.3+ on Windows, Linux, and macOS. Older versions may have different menu paths.
• Remote interpreter troubleshooting assumes SSH access and a functioning deployment configuration.
• External environment managers (Poetry, Pipenv, Conda) can introduce wrapper-script issues not fully addressed here; consult their documentation for the correct interpreter path.