Introduction

The error ImportError: No module named 'yaml' means Python cannot find the package that provides the yaml module in the interpreter you are currently running. In almost every case, the fix is to install PyYAML into the correct environment and verify that you are not shadowing the module with a local file.

The Module Name and Package Name Are Different

This error confuses people because the import name is yaml, but the package you install is PyYAML.

In code, you write:

import yaml

But to install it, use:

python -m pip install pyyaml

Using python -m pip is important because it installs the package into the same interpreter you are invoking, which avoids many environment mismatches.

Verify the Environment First

The most common cause is installing PyYAML into one Python environment and running your program with another.

Check both the interpreter and the package:

python --version
python -m pip show pyyaml
python -c "import yaml; print(yaml.__file__)"

If pip show cannot find the package, it is not installed in that interpreter. If the import prints a path you did not expect, you may be using a different environment than you thought.

Virtual Environments Cause Many of These Errors

If your project uses a virtual environment, activate it before installing:

1python -m venv .venv
2source .venv/bin/activate
3python -m pip install pyyaml
4python -c "import yaml; print('ok')"

On Windows, activation is different:

.venv\Scripts\Activate.ps1
python -m pip install pyyaml

The important point is consistency. Install and run with the same interpreter.

Watch Out for Local Files Named yaml.py

Another surprisingly common cause is name shadowing. If your project contains a file named yaml.py or a folder named yaml, Python may try to import that instead of the third-party package.

This small directory layout can break imports:

project/
  yaml.py
  app.py

If app.py contains import yaml, Python may load the local yaml.py file instead of PyYAML. Rename the local file and delete any stale __pycache__ directories if needed.

A Minimal Working Example

Once PyYAML is installed correctly, this should work:

1import yaml
2
3text = """
4name: codemia
5features:
6  - search
7  - rewrite
8"""
9
10data = yaml.safe_load(text)
11print(data["name"])
12print(data["features"])

Use safe_load unless you specifically need advanced YAML object construction. For configuration files, safe_load is usually the right default.

ImportError vs ModuleNotFoundError

In modern Python versions, you may see ModuleNotFoundError instead of the older ImportError wording. For this problem, the meaning is effectively the same: Python could not resolve the yaml module.

So do not get distracted by the exact exception subclass. The troubleshooting steps remain:

• confirm the interpreter
• confirm the package install
• confirm there is no local shadowing

Common Pitfalls

The biggest pitfall is running pip install pyyaml in one terminal and launching the script with a different interpreter from an IDE, notebook kernel, or virtual environment.

Another issue is installing the wrong package name. The import is yaml, but the package is PyYAML.

Local files named yaml.py also cause confusion because the error looks like a missing package when it is actually a name collision inside the project.

Summary

• The yaml module usually comes from the PyYAML package.
• Install it with python -m pip install pyyaml in the same interpreter you use to run the code.
• Verify the environment with python -m pip show pyyaml and a quick import test.
• Check for local files or folders named yaml that shadow the real package.
• Prefer yaml.safe_load() for ordinary configuration parsing.