Tools and workflows

How to lint Python in VS Code and the terminal

Find Python lint messages in the Problems panel, reproduce them with ruff check, and decide when to fix or narrowly suppress a rule.

Python linting checks source for patterns such as undefined names and unused imports. In VS Code, install the linter extension your project uses and look for its diagnostics in Problems. If the project uses Ruff, ruff check path/to/module.py lets you reproduce a finding in the terminal without changing the file.

Read the rule, file, and line before fixing a warning

Suppose an editor underlines counts in return sum(counts). The message says the name is undefined. Open the Problems panel and check the file, line, and rule code. Then trace the name back to its assignment or parameter. In a function declared as def total(count):, the issue might be the mismatched parameter name. Changing the name requires understanding which value the function should receive.

An unused import message is different. If an import has no purpose, remove it and run the appropriate checks. If a package exports a symbol from its initializer for callers, document the intended public export through the project's supported conventions. The diagnostic can be useful in both cases, even though the right edit differs.

Get a diagnostic in the editor

Open the workspace and install the linter extension named in the project's contributor instructions. For a Ruff project, use the extension that supports Ruff rather than looking for an older general linting option in the Python extension. Start with a Python file from the project and inspect the Problems panel. Click a finding to jump to its location. Save the file before comparing the result to a command-line run.

In a disposable scratch file, write a two-line function that returns an undefined name. The editor and the terminal check should both point to the usage. Fix the name and run the check again. If there is no finding, verify the extension is enabled for the workspace and check its output or logs. Read the configuration to see which rules run instead of assuming a missing warning proves the code has no typo.

Reproduce the finding on demand

Use the project's own command. In a workspace that uses Ruff, ruff check path/to/module.py checks a single file without applying fixes. Run from the intended project folder so the tool can find the correct configuration. If the same issue appears in VS Code and the terminal, the result is easy to share.

If the editor shows a diagnostic the terminal does not, read the message's source. A type checker can underline a line that Ruff accepts. An unsaved edit can also explain why only the editor sees the issue. Save the file and compare the tool version, configuration, and rule before changing the code.

Start with a manageable rule set

A new lint configuration can report many issues across a large project. Start by identifying which findings signal probable errors and which are conventions your team needs to decide. Apply a small agreed set, establish a baseline, and add stronger rules when you can explain what they catch.

Use a narrow suppression only when the code deliberately violates a rule and there is a reason future readers need to know. A comment naming the specific rule preserves more of the check than disabling all findings for a file. Document why the reported pattern is intentional. A suppression that says merely “lint is wrong here” does not help a reviewer evaluate it.

Decide how to fix an intentionally public import

Suppose reporting.__init__ imports Summary so callers can write from reporting import Summary. A linter may interpret the import as unused because the initializer does not call it. Deleting it would break the public import. Check the project's public API before accepting the editor's quick fix. With Ruff, adding the intended name to an explicit __all__ is one supported way to express a public export. The project should also have a test or example of the public import.

Compare this with a stray import in a private helper left over after a refactor. If it has no purpose or needed effect, removing it is clearer. Two similar warnings can describe different situations. The source boundary and the documented use decide which fix applies.

Choose where to report a violation

An editor diagnostic is useful early feedback. An automated check gives a contributor the same rule regardless of editor. Put enforcement rules in the project, then use the editor to make them easier to see. Do not enable every extension that advertises a Python check. When two extensions report different findings on the same line, identify their source first so you can decide which problem you are looking at.

For a rule migration, consider introducing one category at a time. Select an example of each common finding and show what a good correction looks like. A migration that fixes actual undefined names before reworking every style convention makes behavior changes easier to isolate.

Review fixes before committing them

Keep the first lint review read-only. Some tools can fix supported findings automatically, such as removing an unused import. When applying a fix, inspect the diff and run the affected tests. A tool's classification of a fix as safe is not a claim about every project's assumptions.

Finally, record the repeatable command in the contributor notes. If an editor extension disappears or stops discovering the workspace, the terminal command is a reliable way to continue. A lint pass is evidence that the configured rules found no issues in the checked files. It still leaves decisions about behavior, security, and data interpretation to focused tests and human review.

Sources and further reading

Related reading

Browse Tools and workflows · Explore project tutorials

Search PythonProjects.org