Understanding python.analysis.importFormat in Pylance

June 23, 2026 ยท View on GitHub

Pylance is a fast, feature-rich language server extension for Python in Visual Studio Code, powered by the Pyright static type checker. It provides type checking, completions, navigation, and code actions that help keep imports consistent across a codebase.

The python.analysis.importFormat setting controls how Pylance formats new import statements.

What python.analysis.importFormat does

python.analysis.importFormat tells Pylance whether it should prefer absolute or relative imports when it creates new import statements.

Accepted values:

  • absolute (default)
    • Use absolute import format when creating new import statements.
  • relative
    • Use relative import format when creating new import statements.

Example:

"python.analysis.importFormat": "relative"

Absolute and relative imports

With absolute, Pylance prefers imports such as:

from mypackage.subpackage.module import MyClass

With relative, Pylance prefers imports such as:

from .module import MyClass
from ..subpackage.module import MyClass

Where this setting is used

Pylance uses python.analysis.importFormat when it creates or rewrites imports through features such as:

  • auto-import suggestions
  • import-adding code actions
  • the source.convertImportFormat whole-file code action
  • source.fixAll.pylance when python.analysis.fixAll includes source.convertImportFormat

Use with the Convert Import Format code action

Pylance exposes a whole-file source action named source.convertImportFormat.

That code action rewrites imports in the current file to match python.analysis.importFormat.

For example, if you set:

"python.analysis.importFormat": "relative"

then running Convert Import Format rewrites eligible imports in the file toward relative form.

If you set:

"python.analysis.importFormat": "absolute"

the same code action rewrites eligible imports toward absolute form.

Use with Pylance Fix All

If you want Pylance Fix All to convert imports automatically, include source.convertImportFormat in python.analysis.fixAll:

{
    "python.analysis.importFormat": "relative",
    "python.analysis.fixAll": ["source.convertImportFormat"]
}

When you then run source.fixAll.pylance, Pylance applies import-format conversion using the format selected in python.analysis.importFormat.

Use on save in VS Code

If you want this behavior to run on save through Pylance Fix All, combine python.analysis.fixAll with editor.codeActionsOnSave:

{
    "python.analysis.importFormat": "relative",
    "python.analysis.fixAll": ["source.convertImportFormat"],
    "[python]": {
        "editor.codeActionsOnSave": {
            "source.fixAll.pylance": "explicit"
        }
    }
}

With that configuration, saving a Python file runs Pylance Fix All, and the import-format conversion uses the format selected by python.analysis.importFormat.

Important behavior with relative

Setting python.analysis.importFormat to relative does not mean every import becomes relative.

Pylance only generates relative imports for non-library imports where a relative module path can be formed from the current file. Standard library and third-party imports remain absolute.

This matters in layouts such as:

  • multiple top-level packages in one workspace
  • separate tests folders
  • workspaces where some imports cross package boundaries

In those cases, some imports may still stay absolute, and that is expected.

Choosing between absolute and relative

Use absolute when:

  • your project style prefers fully qualified imports
  • your workspace contains multiple top-level packages
  • relative imports often cross boundaries that should stay absolute

Use relative when:

  • your project prefers package-local relative imports
  • most imports stay within the same package tree
  • you want auto-imports and import-conversion actions to follow that style where possible

Frequently asked questions

Why are some imports still absolute when python.analysis.importFormat is set to relative?

Because Pylance does not convert library imports to relative form, and some user-code imports do not have a valid relative path from the current file.

Why did Convert Import Format not rewrite an import the way I expected?

In multi-package or test-folder layouts, the import that looks "local" in the workspace may still need to remain absolute to match package boundaries.

Does this setting change existing imports by itself?

No. It affects how Pylance formats new imports and how import-conversion actions behave. Existing imports change only when you apply a code action such as source.convertImportFormat or run Pylance Fix All with source.convertImportFormat enabled.

Does this setting affect third-party and standard library imports?

It affects the formatting choice for new imports, but standard library and third-party imports remain absolute rather than being rewritten as relative imports.

For more information on Pylance settings and customization, refer to the Pylance Settings and Customization documentation.