Introduction

The error ImportError: No module named 'yaml' means Python cannot find the YAML library in the interpreter you are running. The fix is almost always one of three things: install the PyYAML package into the correct environment, verify you are not accidentally running a different Python interpreter, or rename a local file that shadows the real module.

The confusion starts with a naming mismatch. You write import yaml in code, but the package on PyPI is called PyYAML, not yaml. That single fact trips up a large number of developers.

Install PyYAML Into the Correct Interpreter

The safest install command uses python -m pip rather than bare pip, because it guarantees the package lands in the same interpreter you will use to run your script.

python -m pip install pyyaml

If you are on a system where python3 is the correct binary (common on macOS and many Linux distributions), use that instead:

python3 -m pip install pyyaml

After installation, verify it immediately:

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

The pip show command confirms the package is installed, and the import test confirms the interpreter can actually load it.

Why the Package Name and Import Name Differ

Many Python packages use a different name on PyPI than the module you import. PyYAML installs a module named yaml. This is a convention, not a bug, but it creates a common trap.

Here is a short reference of similar cases:

Running pip install yaml will either fail or install a completely different, unmaintained package. Always install pyyaml.

Virtual Environment Mismatches

The most frequent root cause is installing PyYAML into one Python environment while running your script in another. This happens constantly with virtual environments, Conda environments, and system vs. user installs.

Creating and activating a virtual environment

1python -m venv .venv
2source .venv/bin/activate      # macOS/Linux
3# .venv\Scripts\Activate.ps1   # Windows PowerShell
4python -m pip install pyyaml
5python -c "import yaml; print('ok')"

Diagnosing which interpreter is active

which python          # macOS/Linux
where python          # Windows
python -c "import sys; print(sys.executable)"

If the path printed by sys.executable does not match the environment where you installed pyyaml, you have found the problem. Activate the correct environment or reinstall into the one you are actually using.

IDE interpreter mismatch

VS Code, PyCharm, and other IDEs maintain their own interpreter setting independently of your terminal. If the IDE is configured to use the system Python but your terminal activates a virtual environment (or vice versa), the import will fail in one context and succeed in the other. Check the IDE's Python interpreter selector to make sure it points to the same environment.

Local File Shadowing

If your project contains a file named yaml.py or a directory named yaml/, Python's import system may load that instead of the real PyYAML package.

project/
  yaml.py        <-- this shadows the real package
  app.py

When app.py runs import yaml, Python finds the local yaml.py first because the current directory is at the front of sys.path. The fix is to rename the local file and delete any cached bytecode:

mv yaml.py yaml_config.py
rm -rf __pycache__

You can verify what Python actually loaded by checking the module path:

import yaml
print(yaml.__file__)

If the path points to your project directory instead of the site-packages directory, shadowing is the problem.

A Working Example

Once PyYAML is correctly installed, here is a minimal round-trip example showing both loading and dumping:

1import yaml
2
3# Parse YAML from a string
4text = """
5database:
6  host: localhost
7  port: 5432
8  credentials:
9    user: admin
10    password: secret
11"""
12
13config = yaml.safe_load(text)
14print(config["database"]["host"])   # localhost
15print(config["database"]["port"])   # 5432
16
17# Dump a Python dict back to YAML
18output = yaml.dump(config, default_flow_style=False)
19print(output)

Use safe_load and safe_dump by default. The older yaml.load() without a Loader argument is deprecated and unsafe because it can execute arbitrary Python objects embedded in the YAML.

Reading YAML Files From Disk

A common real-world pattern is loading a configuration file:

1import yaml
2from pathlib import Path
3
4config_path = Path("config.yml")
5
6with config_path.open() as f:
7    config = yaml.safe_load(f)
8
9print(config)

If you need to write YAML back to disk:

with config_path.open("w") as f:
    yaml.dump(config, f, default_flow_style=False, sort_keys=False)

Passing sort_keys=False preserves the original key order, which is usually what you want for configuration files.

ImportError vs ModuleNotFoundError

In Python 3.6 and later, you may see ModuleNotFoundError instead of the older ImportError. ModuleNotFoundError is a subclass of ImportError, so any except ImportError block will still catch it. The troubleshooting steps are identical regardless of which exception name appears.

1try:
2    import yaml
3except ImportError:
4    print("PyYAML is not installed. Run: python -m pip install pyyaml")
5    raise

Docker and CI Environments

In containerized or CI environments, the error often appears because pyyaml is missing from the requirements.txt or the Docker image's install step.

1FROM python:3.12-slim
2WORKDIR /app
3COPY requirements.txt .
4RUN pip install --no-cache-dir -r requirements.txt
5COPY . .
6CMD ["python", "app.py"]

Make sure pyyaml appears in requirements.txt:

pyyaml>=6.0

In CI pipelines, the same principle applies. The install step must run before any script that imports yaml.

Common Pitfalls

Installing with bare pip instead of python -m pip. If multiple Python versions are installed, bare pip may point to a different interpreter than the one running your script. Always prefer python -m pip.

Installing the wrong package. Running pip install yaml installs a different, largely abandoned package. The correct package is pyyaml.

Forgetting to activate the virtual environment. The package is installed inside the venv, but the script runs with the system Python because the venv was not activated in the current shell session.

Shadowing with a local file. A file named yaml.py in the project directory intercepts the import before Python reaches site-packages.

Stale bytecode cache. Even after renaming a shadowing file, Python may still load the old __pycache__/yaml.cpython-*.pyc. Delete the __pycache__ directory to force a fresh import.

Summary

• The yaml module comes from the PyYAML package. Install it with python -m pip install pyyaml.
• Use python -m pip to ensure the package is installed into the interpreter you are actually using.
• Check for virtual environment mismatches by comparing sys.executable with the environment where the package is installed.
• Rename any local files or directories named yaml that could shadow the real package, and delete __pycache__.
• Use yaml.safe_load() and yaml.safe_dump() for configuration parsing. Avoid the unsafe yaml.load() without an explicit Loader.
• In Docker and CI, add pyyaml to requirements.txt so it is installed during the build step.