How to Configure Auto-Imports in Pylance

Pylance can automatically suggest and add import statements when you use a symbol that isn't imported yet. This guide explains the settings that control auto-import behavior, how to tune them for your project, and how to troubleshoot common issues.

---

Table of Contents

• How Auto-Imports Work
• Enable or Disable Auto-Import Completions
• Control Import Style
• Control Which Symbols Appear
• Improve Auto-Import Coverage with Indexing
• Too Many Suggestions
• Missing Suggestions
• Organize Imports on Save
• Diagnostic Checklist
• FAQ

---

How Auto-Imports Work

When you type a symbol name, Pylance searches:

1. Open files and the current project for matching symbols.
2. Indexed packages (if indexing is enabled) for library symbols.
3. Standard library stubs for built-in module symbols.

Matches appear in the completion list with an import icon. Accepting one inserts the import statement at the top of the file.

Auto-imports also work through quick fixes: if you write code with an unresolved name, Pylance offers an "Add import" code action (light bulb).

---

Enable or Disable Auto-Import Completions

python.analysis.autoImportCompletions controls whether auto-import suggestions appear in the completion list.

{
    "python.analysis.autoImportCompletions": true
}

Value	Behavior
true	Auto-import suggestions appear in completions
false (default for "default" mode)	Auto-import suggestions are hidden from completions, but quick-fix "Add import" still works

Even with autoImportCompletions disabled, you can still trigger auto-imports via the code action (light bulb / Ctrl+.).

---

Control Import Style

python.analysis.importFormat controls whether auto-imports use absolute or relative style:

{
    "python.analysis.importFormat": "absolute"
}

Value	Result
"absolute" (default)	from mypackage.utils import helper
"relative"	from .utils import helper

Relative imports are only used when the file and the target symbol are in the same package.

---

Control Which Symbols Appear

Include Re-exports from User Files

python.analysis.includeAliasesFromUserFiles controls whether re-exported symbols from your own code appear in auto-imports:

{
    "python.analysis.includeAliasesFromUserFiles": true
}

When true, if mypackage/__init__.py imports helper from mypackage._internal, Pylance will suggest from mypackage import helper in completions.

Control Package Indexing Depth

python.analysis.packageIndexDepths lets you control how deeply Pylance indexes specific packages:

{
    "python.analysis.packageIndexDepths": [
        { "name": "numpy", "depth": 2 },
        { "name": "pandas", "depth": 2 },
        { "name": "sklearn", "depth": 3, "includeAllSymbols": true }
    ]
}

Property	Meaning
depth	How many subpackage levels to index (default: 1 for most packages)
includeAllSymbols	Include non-__all__ symbols (default: false)

Increase depth for packages where auto-imports miss deeply nested symbols.

How default depths vary by language server mode

In default mode, most packages are indexed at depth 1 (top-level only). A few popular libraries (sklearn, matplotlib, scipy, django, flask, fastapi) default to depth 2, and cuda defaults to depth 3 with includeAllSymbols: true.

In full mode, all packages default to depth 4 with includeAllSymbols: true, providing much broader auto-import coverage at the cost of higher resource usage.

In light mode, indexing is disabled by default. Enable python.analysis.indexing explicitly to use package indexing in light mode.

Automatic depth boost for direct dependencies

Packages declared in requirements.txt or pyproject.toml are automatically indexed at depth 2, even when the global default is 1. Explicit entries in packageIndexDepths take priority over the automatic boost. See the packageIndexDepths setting page for details.

Namespace packages

PEP 420 namespace packages (e.g., azure, google) lack an __init__.py at the top level. Pylance automatically looks up to 4 levels deep to find the first real subpackage, so from azure.storage.blob import BlobClient works even at the default depth of 1. See the packageIndexDepths setting page for details.

---

Improve Auto-Import Coverage with Indexing

python.analysis.indexing enables background indexing, which pre-scans installed packages for symbols:

{
    "python.analysis.indexing": true
}

Without indexing, Pylance only knows about symbols from files it has already opened or analyzed. With indexing, it proactively discovers symbols across your installed packages.

Scenario	Indexing recommended?
Large project with many dependencies	Yes — significantly improves auto-import quality
Small script, few dependencies	Optional — auto-imports work reasonably without it
languageServerMode "light"	Indexing defaults to false; enable explicitly if needed

Related indexing settings

• persistAllIndices — cache indices to disk for faster startup
• userFileIndexingLimit — limit the number of user files indexed
• regenerateStdLibIndices — force re-index of standard library

---

Too Many Suggestions

Symptom: Completion list is cluttered with symbols from packages you don't use.

Fixes

1. Show only direct dependencies — enable showOnlyDirectDependenciesInAutoImport to limit auto-import completions to packages declared in requirements.txt or pyproject.toml:

   {
       "python.analysis.showOnlyDirectDependenciesInAutoImport": true
   }
   

2. Reduce packageIndexDepths for noisy packages:

   {
       "python.analysis.packageIndexDepths": [{ "name": "noisy_package", "depth": 1 }]
   }
   

3. Disable auto-import completions and rely on quick fixes instead:

   {
       "python.analysis.autoImportCompletions": false
   }
   

4. Exclude directories you don't want indexed:

   {
       "python.analysis.exclude": ["vendor/**", "third_party/**"]
   }
   

---

Missing Suggestions

Symptom: Typing a known symbol doesn't show an auto-import suggestion.

Common Causes and Fixes

Cause	Fix
Indexing disabled	Set indexing to true
autoImportCompletions is false	Set autoImportCompletions to true
Package not installed in selected environment	Install the package in the active interpreter's environment
Symbol is deeply nested	Increase depth in packageIndexDepths. Direct dependencies declared in requirements.txt/pyproject.toml are automatically indexed deeper
Symbol is not in __all__	Set includeAllSymbols: true in packageIndexDepths for that package
Private symbol (underscore prefix)	Pylance hides private symbols by default. Import manually
languageServerMode is "light"	Switch to "default" or "full" for better indexing
Symbol only available through a re-export	Enable includeAliasesFromUserFiles

---

Organize Imports on Save

VS Code can automatically sort and remove unused imports when you save. This works alongside auto-imports.

Add to .vscode/settings.json:

{
    "editor.codeActionsOnSave": {
        "source.organizeImports.pylance": "explicit"
    }
}

This runs Pylance's import organizer on save. It:

• Sorts imports alphabetically
• Groups imports by standard lib → third-party → local
• Removes unused imports

See python.analysis.fixAll for other code actions available on save.

Note: Pylance's organizer handles sorting and removing unused imports. For more advanced import formatting (custom grouping rules, blank lines between groups, line length), consider using isort or Ruff as a complementary tool.

Example settings.json for using Ruff as the import organizer instead of Pylance:

{
    "editor.codeActionsOnSave": {
        "source.organizeImports.ruff": "explicit"
    },
    "[python]": {
        "editor.defaultFormatter": "charliermarsh.ruff"
    }
}

With isort, configure it in pyproject.toml:

[tool.isort]
profile = "black"
known_first_party = ["mypackage"]
sections = ["FUTURE", "STDLIB", "THIRDPARTY", "FIRSTPARTY", "LOCALFOLDER"]

---

Diagnostic Checklist

When auto-imports aren't working as expected:

• Indexing enabled: python.analysis.indexing is true
• Auto-import completions enabled: python.analysis.autoImportCompletions is true
• Correct interpreter: Package is installed in the selected Python environment
• Indexing complete: Check Output → Pylance — auto-imports improve after indexing finishes
• Language server mode: Not set to "light" (limits indexing)
• Config file: No pyrightconfig.json overriding VS Code settings unexpectedly. See Settings Troubleshooting

---

FAQ

Q: Why does auto-import suggest a long path instead of the short one?

Pylance suggests the path where the symbol is defined, not necessarily the re-export path. To prefer shorter paths:

• Enable includeAliasesFromUserFiles — this makes re-exported symbols available through the shorter path.
• Libraries that define __all__ in their __init__.py usually provide the short path by default.

Q: Can I auto-import from packages in extraPaths?

Yes. Packages found through extraPaths are treated like installed packages for auto-import purposes.

Q: Does auto-import work with pyrightconfig.json?

Auto-import settings like autoImportCompletions are not overridden by pyrightconfig.json. They remain controlled by VS Code settings. However, path settings (extraPaths, include, exclude) in the config file do affect which symbols are available.

Q: How do I make auto-import prefer from X import Y style?

This is the default behavior. Pylance generates from module import name style imports. There is currently no setting to switch to import module style for auto-imports.

---

Related Guides

• How to Fix Unresolved Import Errors — when imports don't resolve at all
• How to Tune Pylance Performance — indexing and memory management
• Settings Troubleshooting — config file precedence

---

This document was generated with the assistance of AI and has been reviewed by humans for accuracy and completeness.