Introduction

When Pylint says it cannot import a module, the problem is usually that Pylint is running with a different import path than your application or test runner. Setting PYTHONPATH can solve it, but it is often better to fix the project structure, use the correct virtual environment, or run Pylint from the project root so imports resolve naturally.

Why the Error Happens

Pylint imports modules to analyze them. If the module search path does not include your package root, or if Pylint is using the wrong interpreter, it reports an import error even when the code works elsewhere.

Typical causes include:

• running Pylint from the wrong directory
• missing virtual environment activation
• source tree not installed as a package
• IDE linter using a different interpreter than the shell

First Try Running From the Project Root

Suppose your layout is:

1project/
2  src/
3    myapp/
4      __init__.py
5      service.py
6  tests/

A common fix is to run Pylint from project and point it at the package.

cd project
PYTHONPATH=src pylint src/myapp

That tells Python and Pylint to treat src as an import root.

Set PYTHONPATH Temporarily

On Unix-like shells:

export PYTHONPATH=src
pylint src/myapp

On Windows PowerShell:

$env:PYTHONPATH = "src"
pylint src/myapp

This is fine for quick local testing, but it can be brittle if every developer has to remember it manually.

Use a Pylint Init Hook

If you want Pylint to add a path automatically, you can configure an init hook.

In .pylintrc:

[MASTER]
init-hook='import sys; sys.path.append("src")'

This makes Pylint extend sys.path before analysis begins.

Better Long-Term Fix: Install the Package

If the code is a real Python package, a better long-term solution is often editable installation.

pip install -e .

Then Pylint, your test runner, and your application all see the same package layout through the active environment.

This usually beats managing ad hoc PYTHONPATH values everywhere.

Verify the Interpreter

If you use a virtual environment, make sure Pylint is installed and executed inside that environment.

which pylint
python -c "import sys; print(sys.executable)"

If those point to different environments than your app uses, Pylint may be importing from the wrong place.

IDE Integration

Editors often run their own linter process. That means fixing the shell environment alone may not fix the IDE.

In practice, you need the IDE configured to:

• use the correct Python interpreter
• treat the proper source directory as the project root
• respect your linter configuration file

Otherwise the IDE may keep reporting missing imports even though the terminal command works.

Package Layout Still Matters

If directories are missing __init__.py where your project structure expects package semantics, import resolution can become inconsistent across tools. Modern namespace packages exist, but many projects are easier to lint and reason about when the package structure is explicit and consistent.

That is why import errors are sometimes a project-layout issue first and a PYTHONPATH issue second.

Common Pitfalls

A common mistake is patching PYTHONPATH everywhere instead of making the project installable or fixing the package layout.

Another mistake is running Pylint from a subdirectory where relative imports no longer resolve as intended.

Developers also often fix the shell command but forget the IDE is using a different interpreter or working directory.

Summary

• The error usually means Pylint's import path differs from your real runtime environment.
• 'PYTHONPATH=src pylint ... is a common quick fix for src layouts.'
• A .pylintrc init hook can make the path change automatic.
• Editable installation with pip install -e . is often the cleaner long-term solution.
• Always verify the interpreter and working directory that Pylint is actually using.