PyCharm跨目录Jump to Declaration功能失效问题求解

I’ve run into this exact issue a bunch of times when working on projects with scattered source directories—PyCharm’s indexing can be picky about which folders it recognizes as part of your codebase. Here’s how to fix it step by step:

• Mark directories as Sources Root
  This is the most common fix. PyCharm only indexes directories marked as "Sources Root" for code navigation. Right-click the directory you want to use for jumps, hover over Mark Directory as, and select Sources Root. You’ll see the directory icon turn blue, which means it’s now part of PyCharm’s code index.

• Verify Project Structure settings
  Sometimes marking via right-click doesn’t stick, or you need to adjust multiple directories at once. Go to File > Project Structure > Modules, then select the Sources tab. Make sure all your source directories are listed here (they’ll be highlighted in blue). If any of your folders are in the Excluded tab by mistake, remove them—excluded folders aren’t indexed at all.

• Invalidate caches and restart
  Corrupted index caches are another frequent culprit. Head to File > Invalidate Caches..., then choose Invalidate and Restart. PyCharm will clear its cached indexes and rebuild them from scratch when it boots back up. This fixes a ton of weird navigation glitches, including broken jump-to-declaration.

• Check your Python interpreter configuration
  Ensure you’re using the correct interpreter (especially if you’re using a virtual environment). Go to File > Settings > Project: [Your Project Name] > Python Interpreter. Click the gear icon and select Show All—check that your source directories are included in the interpreter’s path (though marking them as Sources Root usually handles this automatically). If you’re using a virtual env, make sure it’s activated in PyCharm.

• Double-check your import syntax
  If you’re using relative imports (like from ..utils import helper_func), make sure your directory structure matches the import hierarchy. Alternatively, if you’ve marked parent directories as Sources Root, you can use absolute imports (like from my_project.utils import helper_func) which are more reliable for PyCharm’s navigation. Avoid naming directories/files the same as standard library modules (e.g., json or requests)—this can confuse PyCharm’s indexing.

If none of these work, try closing the project and re-opening it, or even deleting the .idea folder (PyCharm will recreate it when you open the project again) as a last resort.

内容的提问来源于stack exchange，提问作者LampShade