Pylint

Pylint is a static code analysis tool for Python. It checks code for errors, style problems, naming issues, unused imports, unused variables, refactoring suggestions, and other quality problems without executing your program. You run it on source files or packages, read the messages it reports, fix real issues, and tune rules in project config when a check does not fit your codebase.

Tested on: Python 3.13.3; Pylint 4.0.6; kernel 6.14.0-37-generic.

Quick answer: run Pylint on Python code

Install Pylint with pip install pylint. Run it with pylint file.py. Fix reported messages, or disable and configure rules when they do not fit your project.

python -m venv .venv
source .venv/bin/activate
pip install pylint
pylint app.py

Use a virtual environment for project work. Install Pylint in the same environment where your code runs, and list it in your pip requirements file when the team shares dependencies.

Pylint quick reference

What is Pylint?

Pylint reads Python source and reports problems before runtime. It can catch unused imports, bad names, undefined variables, overly complex functions, missing docstrings, and patterns that often lead to bugs. At the end of a run it also prints a score out of 10.

Pylint is useful in three common places:

• On your machine while editing code
• In your editor through the Pylint extension
• In CI to block merges when quality drops below a threshold

It complements formatters such as Black and type checkers such as mypy. Pylint focuses on conventions and code quality; it does not replace formatting or full static typing on its own.

Install and run Pylint

Install in a virtual environment

python -m venv .venv
source .venv/bin/activate
pip install pylint
pylint --version

Sample output:

pylint 4.0.6
astroid 4.0.4
Python 3.13.3 ...

You can also run python -m pip install pylint. Some Linux distributions ship python3-pylint, but pip inside a project venv is usually the better default for application work.

Run on one file

pylint app.py

Pylint prints one line per issue with path, line, column, message code, symbolic name, and message text. A clean file may end with:

Your code has been rated at 10.00/10

The score starts at 10 and goes down as issues are found. Treat the score as a rough signal, not the main goal. Fixing useful warnings matters more than chasing a perfect number on the first run.

Run on a package or project

pylint mypackage
pylint src/mypackage/module.py
pylint -j 4 mypackage

Run Pylint from the project root when local imports depend on your package layout. If import errors appear even though the code runs, try:

• installing the project in editable mode: pip install -e . (see create a Python package)
• linting from the repository root
• setting PYTHONPATH for src-layout projects

Understand Pylint output and score

Sample message:

app.py:3:0: C0103: Function name "myFunction" doesn't conform to snake_case naming style (invalid-name)

Format: path:line:column: CODE: message (symbol)

Use symbolic names such as invalid-name in config and disable comments. They are easier to maintain than message codes alone.

To fail a CI job when the score is too low:

pylint --fail-under=8.0 src/mypackage

Pylint exits with a non-zero status when the score is below the threshold.

Work through a Pylint example

Start with a small file that triggers common beginner messages. Naming issues often involve Python functions and variables that do not follow snake_case:

import os

def myFunction():
    unused = 42
    return "done"

Run:

pylint demo.py

Sample output:

demo.py:1:0: C0114: Missing module docstring (missing-module-docstring)
demo.py:3:0: C0116: Missing function or method docstring (missing-function-docstring)
demo.py:3:0: C0103: Function name "myFunction" doesn't conform to snake_case naming style (invalid-name)
demo.py:4:4: W0612: Unused variable 'unused' (unused-variable)
demo.py:1:0: W0611: Unused import os (unused-import)

Your code has been rated at 0.00/10

Apply these fixes:

• Rename myFunction to my_function
• Remove the unused os import and unused variable
• Add docstrings, or disable docstring rules if your project does not require them

Fixed version:

"""Demo module for pylint."""

def my_function():
    """Return done."""
    return "done"

After fixes, the same file can score 10.00/10 on a clean run.

Fix common Pylint warnings

invalid-name and snake_case naming

The message doesn't conform to snake_case naming style is usually C0103 / invalid-name.

Naming expectations:

• Functions and variables: snake_case
• Classes: PascalCase
• Constants: UPPER_CASE

Rename the object when Pylint is correct. Change project naming rules or disable invalid-name only when your codebase intentionally uses another style.

PEP 8 recommends lowercase function names with underscores between words. The Pylint invalid-name docs describe supported naming styles such as snake_case, camelCase, PascalCase, UPPER_CASE, and any.

Messages beginners see most often

When a message is valid but not worth fixing in a script or test file, disable it locally instead of weakening project-wide rules.

Disable and configure Pylint

Disable warnings inline or from the CLI

Prefer fixing the code first. Disable a rule only when it is not useful for that line, file, or project.

Inline disable for the current line:

def myFunction():  # pylint: disable=invalid-name
    return "done"

Disable for the next line:

# pylint: disable-next=invalid-name
def myFunction():
    return "done"

Disable for an entire file when appropriate:

# pylint: disable=missing-module-docstring
import sys

Command-line disable:

pylint --disable=invalid-name demo.py

See Pylint message control.

Enable only selected checks

On legacy codebases, lint only the rules you care about first:

pylint --disable=all --enable=unused-import,unused-variable,undefined-variable src/

This is often easier than disabling dozens of noisy rules one by one.

Project config with pyproject.toml

Use pyproject.toml for modern project config. .pylintrc is still common in older projects.

Generate a starting config:

pylint --generate-toml-config > pyproject-snippet.toml
pylint --generate-rcfile > .pylintrc

Treat generated files as a starting point, not something to paste blindly into every repo.

Minimal example:

[tool.pylint.messages_control]
disable = [
    "missing-module-docstring",
    "missing-function-docstring",
]

[tool.pylint.format]
max-line-length = 100

[tool.pylint.basic]
good-names = ["i", "j", "k", "ex"]

Scripts, tutorials, and tests often disable docstring rules that libraries keep enabled. See the Pylint configuration guide.

Use Pylint in editors and automation

Pylint in VS Code

Install the Microsoft Pylint extension. Do not rely on the deprecated "python.linting.pylintEnabled": true setting.

Basic workflow:

1. Install the Pylint extension
2. Select the same Python interpreter or virtual environment as your project
3. Open a Python file and review diagnostics in the Problems tab

If imports fail in the editor but work in your terminal, recheck interpreter selection and workspace folder paths. You can pass extra args through extension settings when needed, for example to lint a src layout consistently.

Pylint in CI

A minimal GitHub Actions step:

- run: pip install pylint
- run: pylint --fail-under=8.0 src/mypackage

Do not force a perfect 10/10 score immediately on legacy codebases. Common rollout patterns:

• Start with --disable=all --enable=... for a small rule set
• Add a --fail-under threshold and raise it over time
• Exclude generated code, migrations, and vendored paths

Pylint with pre-commit

Optional local hook example:

repos:
  - repo: https://github.com/pylint-dev/pylint
    rev: v4.0.6
    hooks:
      - id: pylint
        args: ["--fail-under=8.0"]
        files: ^src/

Keep hooks focused on the paths and rules you actually want enforced.

Pylint vs other Python tools

Many teams use one linter plus one formatter. Some newer projects choose Ruff for speed and keep Pylint only where its deeper analysis is worth the runtime cost.

When to use Pylint (and when to tune it down)

Use Pylint when you want naming consistency, unused-code detection, convention checks, and project-specific lint rules in CI.

Pylint can feel noisy on:

• One-off scripts and tutorial examples
• Test files with long fixture names
• Notebook exports and data-science notebooks
• Generated code and migrations

Tune it deliberately:

• Disable specific rules in pyproject.toml for tests or scripts
• Use file-level # pylint: disable=... sparingly
• Avoid turning off broad categories globally just to reach 10/10

Summary

Pylint checks Python code without running it. Install it with pip install pylint, then run pylint file.py or pylint package_name. Fix real issues first, then configure or disable rules when needed. Use pyproject.toml or .pylintrc for project-wide settings, --fail-under for CI thresholds, and the VS Code Pylint extension for editor integration.

References

• Pylint documentation
• Pylint invalid-name message
• Pylint message control
• PEP 8 style guide
• Microsoft Pylint VS Code extension