Configuring linting - Python and pylance extensions, and the ruff and black extensions

[pfmoore]

Until now, I have basically just used VS Code more or less "out of the box" for my Python coding. But I want to start standardising on ruff as my linter, replacing flake8 and isort, and black as my code formatter (at least until ruff gets auto-formatter functionality). I can easily enough install the ruff plugin, and remove the isort plugin, but to be honest, I'm not at all clear what I need to do with the Python and pylance extensions.

I currently have "Formatting: Provider" set to "autopep8" in my config, but as far as I know I don't have autopep8 installed - does it come with the Python extension or is my config messed up somehow? I have "Linting: Enabled", but the same questions apply as I don't install any linter - and even more confusingly, there doesn't seem to be a "Linting provider" setting, so I'm not sure which linter I'm using in any case... And I don't even know if the ruff and black plugins supply all of the functionality that I currently get from wherever it comes from - things like auto-fix suggestions, auto-indentation, etc. Do I still need to configure the python/pylance plugins to cover areas like that?

There's also some options and actions where I'm not at all clear what is providing them. "Format document" is one (on the right click menu). Will that invoke black? Or how do I configure it to do so? If it uses some other formatter, what's to stop it applying rules that don't match black's? Similarly there's a "Sort Imports" action (which I can only find right now under the command palette as "Python Refactor: Sort Imports") which seems to use different rules than isort (I know I've used it in the past and it's "fixed" things in a way that isort then rejected).

Sorry - this is sort of a "help, I'm confused" rant. Really, what I'm asking is how do I set VS Code up to use black and ruff, or better still, how do I find out what I need to know to understand what's going on well enough to work out for myself how to do it.

I understand that a lot of this is down to the interaction between different extensions, and so there's something of a "not my problem" issue here. But as a user, I honestly don't care who is responsible, all I'm looking for is someone who can help me rationalise things so that I'm just using a single set of tools, and configuring things once in the way I want my project(s) to work.

If there's a better place where I can get support for this sort of question, then I'd love it if someone could point me there. One of the other issues with having so many extensions interacting is that it's very difficult to know where to go to get help with higher level questions like this.

[brettcannon]

does it come with the Python extension or is my config messed up somehow?

It comes with Python for now, but we are moving folks to standalone extensions for formatting, e.g. https://marketplace.visualstudio.com/items?itemName=ms-python.autopep8 .

I have "Linting: Enabled", but the same questions apply as I don't install any linter

Same as above: we are moving folks off of the built-in linter support and over to dedicated extensions.

there doesn't seem to be a "Linting provider" setting

There isn't one because you can run mulitple linters but you can only have one formatter. So you can turn on/off individual linters, e.g. python.linting.pylintEnabled turns on/off Pylint (see the docs).

And I don't even know if the ruff and black plugins supply all of the functionality that I currently get from wherever it comes from - things like auto-fix suggestions

Auto-fixes are going to come from various extensions, but Ruff would be one of them.

auto-indentation

That's coming from Pylance.

"Format document" is one (on the right click menu). Will that invoke black?

It will invoke whichever formatter you have set up as your formatter for Python code.

Or how do I configure it to do so?

You can set "editor.defaultFormatter" to the extension ID of who you want to do your formatting. So if you want Black and want to be specific that it's for Python code, you can set:

"[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter",
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.organizeImports": true
    },
    "editor.formatOnType": true
  },

Some extra settings you might be interested in:

    "editor.rulers": [
      80,  # python-dev
      88   # Black
    ],
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.organizeImports": true  # If you have something like Ruff or isort installed. 
    },
    "editor.formatOnType": true  # Auto-indent from Pylance.
  },

there's a "Sort Imports" action (which I can only find right now under the command palette as "Python Refactor: Sort Imports") which seems to use different rules than isort (I know I've used it in the past and it's "fixed" things in a way that isort then rejected).

That command just runs whatever extension you have set up to handle import sorting; we don't implement anything custom. A common issue we see with isort is people turn it on but forget to turn on its Black-compatible mode, and then the two tools "fight" each other over how imports should look.

how do I set VS Code up to use black and ruff

1. Install https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff
2. Install https://marketplace.visualstudio.com/items?itemName=ms-python.black-formatter
3. Don't have any settings in the "python" setting namespace related to formatting or linting set

[pythoninthegrass]

how do I set VS Code up to use black and ruff

Install https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff
Install https://marketplace.visualstudio.com/items?itemName=ms-python.black-formatter
Don't have any settings in the "python" setting namespace related to formatting or linting set

Not OP, but appreciate the detailed reply @brettcannon! In addition to removing the python namespace formatting and linting configs, I had to set "python.analysis.ignore": ["*"] to disable pylance/pyright static analysis:

"[python]": {
    "editor.insertSpaces": true,
    "editor.tabSize": 4,
    "editor.codeActionsOnSave": {
      "source.organizeImports": true
    },
},
"python.analysis.ignore": ["*"],

[pfmoore]

Cool, thanks for that comprehensive answer. I do have a couple of follow-up questions, though:

I installed the ruff and black extensions as you suggested.

Don't have any settings in the "python" setting namespace related to formatting or linting set

My user settings is as follows - as you see, it's pretty bare bones, and I don't think I added many of these myself, other than by clicking on "do you want X enabled?" dialogs when they pop up (such as the cmake one, I don't think I've ever dome more than look at the odd cmake file, so that's likely just from me shutting up a dialog).

{
    "workbench.iconTheme": "vscode-icons",
    "extensions.ignoreRecommendations": false,
    "vsicons.dontShowNewVersionMessage": true,
    "editor.fontFamily": "CaskaydiaCove Nerd Font, Cascadia Mono PL, Consolas, 'Courier New', monospace",
    "powershell.integratedConsole.showOnStartup": false,
    "terminal.external.windowsExec": "pwsh",
    "python.languageServer": "Pylance",
    "python.showStartPage": false,
    "workbench.startupEditor": "newUntitledFile",
    "python.pythonPath": "C:\\Users\\UK03306\\AppData\\Local\\Programs\\Python\\Python37\\python.exe",
    "workbench.editorAssociations": {
        "*.ipynb": "jupyter-notebook"
    },
    "notebook.cellToolbarLocation": {
        "default": "right",
        "jupyter-notebook": "left"
    },
    "terminal.integrated.defaultProfile.windows": "PowerShell",
    "cmake.configureOnOpen": false,
    "redhat.telemetry.enabled": false,
    "terminal.integrated.scrollback": 10000,
    "python.defaultInterpreterPath": "",
    "[python]": {
        "editor.defaultFormatter": "ms-python.black-formatter",
        "editor.formatOnType": true
    },
    "editor.copyWithSyntaxHighlighting": false,
    "editor.inlayHints.enabled": "offUnlessPressed",
}

The [python] section presumably came from installing the black extension. I don't see anything in here that mentions autopep8, so I guess I'm still not clear how that's the default, or whether it's now switched off. But it's still showing in the GUI version of the settings editor:

On an unrelated note, I think the python.pythonPath and python.defaultInterpreterPath should probably be removed - that pythonPath is way out of date, I guess it came from some messing round I did very early on.

That command just runs whatever extension you have set up to handle import sorting

I still have the isort extension installed at the moment, I'll likely remove it when I work out how to set things up. But ruff doesn't sort imports by default, so I need to work out how to tell VS Code to include that. It might be worth noting that I want a lot of this set up by default, because I often use VS Code to edit standalone Python files that aren't in a project directory, so I don't have a pyproject.toml, or a virtual environment to activate, or anything like that. But I do want a full-featured "base experience" in that case. I also want that so that when I edit files in a project that doesn't have any specific ruff/black/isort/etc config, VS Code still "just works".

Hmm, I just did a quick test and right click "Sort Imports" now prompts me to use ruff or isort. And when I pick ruff, it does it even though command line ruff doesn't by default. So that's rather cool (although a little confusing). I think what's frustrating me here is that a lot seems to happen "by magic" and it's hard for me to understand precisely what's going on.

A common issue we see with isort is people turn it on but forget to turn on its Black-compatible mode, and then the two tools "fight" each other over how imports should look.

Yes, I'm pretty sure I've seen this in the past. What I'm not clear on is how I "turn on Black-compatible mode" globally, so it applies for every Python file I edit, regardless of whether I'm in a project. To be clear, I'm not asking here how to configure command line isort/black, just how to get VS Code to work everywhere without this inconsistency. Maybe I'll configure the command line tools the same, although I might well do that on a per-project basis, as having projects not depend on global config is a good thing¹, and I don't care for standalone files if my editor is the only way I can reformat the code without weird things happening 😉

Footnotes

1. That's also why I want to avoid having anything more than the bare minimum config in VS Code, as I don't want to accidentally have editing things in VS Code result in autoformatting producing code that violates the project standards... ↩

[brettcannon]

The [python] section presumably came from installing the black extension.

It would have come from installing and then running it as the default formatter.

I don't see anything in here that mentions autopep8, so I guess I'm still not clear how that's the default, or whether it's now switched off. But it's still showing in the GUI version of the settings editor

Correct, but it is the default value for that setting so it's just "falling through" that you are seeing it set to autopep8. And having a value there doesn't mean it's turned on as your formatter, just that the setting has a default value (and as I said, it will be going away in the future).

I think the python.pythonPath and python.defaultInterpreterPath should probably be removed - that pythonPath is way out of date, I guess it came from some messing round I did very early on.

python.pythonPath isn't even used anymore.

But ruff doesn't sort imports by default, so I need to work out how to tell VS Code to include that.

That would be some Ruff setting since the Ruff extension tells VS Code it can handle import sorting and it wants to handle it (i.e., we have nothing to do with it).

I also want that so that when I edit files in a project that doesn't have any specific ruff/black/isort/etc config, VS Code still "just works".

It should, but it's up to the individual tools and extensions as to what that looks like. For instance, the Black extension that we created will just run Black, so whatever that would have done if you ran it on that file is what will happen. We can't speak for the Ruff extension, but I assume it's the same situation.

I think what's frustrating me here is that a lot seems to happen "by magic" and it's hard for me to understand precisely what's going on.

You're also coming in the middle of a transition while wanting to know how things work behind the curtains, so it's not the most ideal time to try to understand things. 😉

Anyway, is it "magic" as in when things trigger? Otherwise we have explicitly taken a position that tool configuration is not for us to control and thus we encourage users to set things up however the tool would want it to be set up. For instance, we don't have a "black-formatter.lineLength" setting or anything; you configure Black as normal, we run Black as "normal" (depends if there's an API or if we have to use runpy or something), and we simply act as an integration point between the tool and VS Code.

how I "turn on Black-compatible mode" globally, so it applies for every Python file I edit, regardless of whether I'm in a project.

Either you set up a global isort config or set isort.args to have the appropriate flags necessary (see the docs).

[farzbood]

The Profile feature could be a quick, custom setup for VSCode + Python development environment.