Python settings reference

The Python Extension for Visual Studio Code is highly configurable. This page describes the key settings you can work with.

Refer to User and workspace settings to find our more about working with settings in VS Code generally.

General settings

Setting Default Description
python.condaPath "conda" Path to the conda executable.
python.pythonPath "python" Path to the python interpreter, or the path to a folder containing the Python interpreter. Can use variables like ${workspaceFolder} and ${workspaceFolder}/.venv. Using a path to a folder allows anyone working with a project to create an environment in the .venv folder as appropriate to their operating system, rather than having to specify an exact platform-dependent path. The settings.json file can then be included in a source code repository.
python.disableInstallationCheck false If set to true, disables a warning from the extension if no Python interpreter is installed. On macOS, also disables a warning that appears if you're using the OS-installed Python interpreter. It's generally recommended to install an separate interpreter on macOS.
python.venvPath "" Path to a folder containing virtual environments, in which the extension looks for virtual environments in the first-level subfolders. Example values: ${workspaceFolder}/.pyenv, ${workspaceFolder}\\venv, .\envs, ~/.virtualenvs, and so on, in which case that folder might have immediate subfolders such as env, env2, ds_analysis_env, and so on which are themselves virtual environments.
python.envFile "${workspaceFolder}/.env" Absolute path to a file containing environment variable definitions. See Configuring Python environments - environment variable definitions file.
python.globalModuleInstallation false Specifies whether to install packages for the current user only using the --user command-line argument (the default), or to install for all users in the global environment (when set to true). Ignored when using a virtual environment. For more information on the --userargument, see pip - User Installs.
python.terminal.launchArgs [] Launch arguments that are given to the Python interpreter when you run a file using commands such as Python: Run Python File in Terminal. In the launchArgs list, each item is a top-level command-line element that's separated by a space (quoted values that contain spaces are a single top-level element and are thus one item in the list). For example, for the arguments --a --b --c {"value1" : 1, "value2" : 2}, the list items should be ["--a", "--b", "--c", "{\"value1\" : 1, \"value2\" : 2}\""]. Note that Visual Studio code ignores this setting when debugging because it instead uses arguments from your selected debugging configuration in launch.json.
python.terminal.executeInFileDir false Indicates whether to run a file in the file's directory instead of the current folder.

Workspace symbol (tags) settings

Workspace symbols are symbols in C source code generated by the ctags tool (described on Wikipedia and on ctags.sourceforge.net). To quote Wikipedia, ctags "generates an index (or tag) file of names found in source and header files of various programming languages." Where Python is concerned, ctags makes it easier to jump to defined functions and other symbols in C/C++ extension modules.

Setting
(python.workspaceSymbols.)
Default Description
tagFilePath "${workspaceFolder}/.vscode/tags" Fully qualified path to tag file (an exuberant ctag file), used to provide workspace symbols.
enabled true Specifies whether to enable the Workspace Symbol provider.
rebuildOnStart true Specifies whether to re-build the tags file on start.
rebuildOnFileSave true Specifies whether to re-build the tags file on when saving a Python file.
ctagsPath "ctags" Fully qualified path to the ctags executable; default value assumes it's in the current environment.
exclusionPatterns ["**/site-packages/**"] Pattern used to exclude files and folders from ctags.

Code analysis settings

IntelliSense engine settings

Setting Default Description
python.jediEnabled true Indicates whether to use Jedi as the IntelliSense engine (true) or the Microsoft Python Language Server (false). Note that the language server requires a platform that supports .NET Core 2.1 or newer.
python.jediPath "" Path to folder containing the Jedi library (folder should contain a jedi subfolder).
python.jediMemoryLimit 0 Memory limit for the Jedi completion engine in megabytes. Zero (the default) means 1024MB. -1 disables the memory limit check.

Python Language Server settings

The language server settings apply when python.jediEnabled is false.

Setting
(python.analysis.)
Default Description
diagnosticPublishDelay 1000 The number of milliseconds to wait before transferring diagnostic messages to the problems list.
disabled
errors
warnings
information
[] List of diagnostics messages to suppress or show as errors, warnings, or information. See below for applicable values. The classification of messages affects both what's shown in the Problems window and in the editor (such as the color of the underlining).
logLevel "Error" Defines the types of log messages that language server writes into the Problems window, one of "Error", "Warning", "Information", and "Trace". The "Warning" level implicitly includes "Error"; "Information" implicitly includes "Warning" and "Error"; "Trace" includes all messages.
openFilesOnly true When true, shows only errors and warnings for open files rather than for the entire workspace.
symbolsHierarchyDepthLimit 10 Limits the depth of the symbol tree in the document outline.
typeshedPaths [] Paths to look for typeshed modules (github.com).

The disabled, errors, warnings, and information settings can contain the following values:

Value Default type Message text
"not-callable" Warning (object may not be callable)
"used-before-assignment" Warning (unknown variable '{0}')
"unresolved-import" Warning "Unable to resolve 'module_name'. IntelliSense may be missing for this module."

To suppress the "used-before-assignment" messages, for example, use the setting "python.analysis.disabled": ["used-before-assignment"].

AutoComplete settings

Setting
(python.autoComplete.)
Default Description See also
addBrackets false Specifies whether VS Code automatically adds parentheses (()) when autocompleting a function name. Editing
preloadModules [] Specifies modules to pre-load to improve autocomplete performance. Editing
extraPaths [] Specifies locations of additional packages for which to load autocomplete data. Editing

Formatting settings

Setting
(python.formatting.)
Default Description See also
provider "autopep8" Specifies the formatter to use, either "autopep8", "black", or "yapf". Editing - Formatting
autopep8Path "autopep8" Path to autopep8 Editing - Formatting
autopep8Args [] Arguments for autopep8 where each top-level element that's separated by a space is a separate item in the list. Editing - Formatting
blackPath "black" Path to black Editing - Formatting
blackArgs [] Arguments for black, where each top-level element that's separated by a space is a separate item in the list. Editing - Formatting
yapfPath "yapf" Path to yapf Editing - Formatting
yapfArgs [] Arguments for yapf, where each top-level element that's separated by a space is a separate item in the list. Editing - Formatting

Refactoring - Sort Imports settings

Setting
(python.sortImports.)
Default Description See also
path "" Path to isort script Editing - Refactoring - Sort Imports
args [] Arguments for isort, each argument as a separate item in the array. Editing - Refactoring - Sort Imports

Linting settings

General

Setting
(python.linting.)
Default Description See also
enabled true Specifies whether to enable linting in general. Linting
lintOnSave true Specifies whether to line when saving a file. Linting
maxNumberOfProblems 100 Limits the number of linting messages shown. Linting
ignorePatterns [".vscode/*.py", "**/site-packages/**/*.py"] Exclude file and folder patterns. Linting

Pylint

Setting
(python.linting.)
Default Description See also
pylintEnabled true Specifies whether to enable Pylint. Linting
pylintArgs [] Additional arguments for Pylint, where each top-level element that's separated by a space is a separate item in the list. Linting
python.linting.pylintUseMinimalCheckers true Specifies whether to use the default value for pylintArgs. Linting
pylintPath "pylint" The path to Pylint. Linting
pylintCategorySeverity.convention "Information" Mapping for Pylint convention message to VS Code type. Linting
pylintCategorySeverity.refactor "Hint" Mapping for Pylint refactor message to VS Code type. Linting
pylintCategorySeverity.warning "Warning" Mapping for Pylint warning message to VS Code type. Linting
pylintCategorySeverity.error "Error" Mapping for Pylint error message to VS Code type. Linting
pylintCategorySeverity.fatal "Error" Mapping for Pylint fatal message to VS Code type. Linting

Pep8/pycodestyle

Setting
(python.linting.)
Default Description See also
pep8Enabled false Specifies whether to enable pep8. Linting
pep8Args [] Additional arguments for pep8, where each top-level element that's separated by a space is a separate item in the list. Linting
pep8Path "pep8" The path to pep8. Linting
pep8CategorySeverity.W "Warning" Mapping for pep8 W message to VS Code type. Linting
pep8CategorySeverity.E "Error" Mapping for pep8 E message to VS Code type. Linting

Flake8

Setting
(python.linting.)
Default Description See also
flake8Enabled false Specifies whether to enable flake8. Linting
flake8Args [] Additional arguments for flake8, where each top-level element that's separated by a space is a separate item in the list. Linting
flake8Path "flake8" The path to flake8. Linting
flake8CategorySeverity.F "Error" Mapping for flake8 F message to VS Code type. Linting
flake8CategorySeverity.E "Error" Mapping for flake8 E message to VS Code type. Linting
flake8CategorySeverity.W "Warning" Mapping for flake8 W message to VS Code type. Linting

mypy

Setting
(python.linting.)
Default Description See also
mypyEnabled false Specifies whether to enable mypy. Linting
mypyArgs ["--ignore-missing-imports", "--follow-imports=silent"] Additional arguments for mypy, where each top-level element that's separated by a space is a separate item in the list. Linting
mypyPath "mypy" The path to mypy. Linting
mypyCategorySeverity.error "Error" Mapping for mypy error message to VS Code type. Linting
mypyCategorySeverity.note "Information" Mapping for mypy note message to VS Code type. Linting

pydocstyle

Setting
(python.linting.)
Default Description See also
pydocstyleEnabled false Specifies whether to enable pydocstyle. Linting
pydocstyleArgs [] Additional arguments for pydocstyle, where each top-level element that's separated by a space is a separate item in the list. Linting
pydocstylePath "pydocstyle" The path to pydocstyle. Linting

prospector

Setting
(python.linting.)
Default Description See also
prospectorEnabled false Specifies whether to enable prospector. Linting
prospectorArgs [] Additional arguments for prospector, where each top-level element that's separated by a space is a separate item in the list. Linting
prospectorPath "prospector" The path to prospector. Linting

pylama

Setting
(python.linting.)
Default Description See also
pylamaEnabled false Specifies whether to enable pylama. Linting
pylamaArgs [] Additional arguments for pylama, where each top-level element that's separated by a space is a separate item in the list. Linting
pylamaPath "pylama" The path to pylama. Linting

Unit testing settings

UnitTest framework

Setting
(python.unitTest.)
Default Description See also
unittestEnabled false Specifies whether UnitTest is enabled for unit testing. Unit testing
unittestArgs ["-v", "-s", ".", "-p", "*test*.py"] Arguments to pass to unittest, where each top-level element that's separated by a space is a separate item in the list. Unit testing
cwd null Specifies an optional working directory for unit tests.
outputWindow "Python Test Log" The window to use for unit test output. Unit testing
promptToConfigure true Specifies whether VS Code prompts to configure a test framework if potential tests are discovered. Unit testing
debugPort 3000 Port number used for debugging of UnitTest tests. Unit testing
autoTestDiscoverOnSaveEnabled true Specifies whether to enable or disable auto run test discovery when saving a unit test file.

PyTest framework

Setting
(python.unitTest.)
Default Description See also
pyTestEnabled false Specifies whether pytest is enabled for unit testing. Unit testing
pyTestPath "py.test" Path to pytest. Use a full path if pytest is located outside the current environment. Unit testing
pyTestArgs [] Arguments to pass to PyTest, where each top-level element that's separated by a space is a separate item in the list. When debugging unit tests with pytest-cov installed, include --no-cov in these arguments. Unit testing

Nose framework

Setting
(python.unitTest.)
Default Description See also
nosetestsEnabled false Specifies whether Nose is enabled for unit testing. Unit testing
nosetestPath "nosetests" Path to Nose. Use a full path if PyTest is located outside the current environment. Unit testing
nosetestArgs [] Arguments to pass to Nose, where each top-level element that's separated by a space is a separate item in the list. Unit testing

Next steps

  • Python environments - Control which Python interpreter is used for editing and debugging.
  • Editing code - Learn about autocomplete, IntelliSense, formatting, and refactoring for Python.
  • Linting - Enable, configure, and apply a variety of Python linters.
  • Debugging - Learn to debug Python both locally and remotely.
  • Unit testing - Configure unit test environments and discover, run, and debug tests.