Home › Python

ModuleNotFoundError: No module named 'yaml' (Python) — how to fix

Traceback (most recent call last):
  File "app.py", line 1, in <module>
    import yaml
ModuleNotFoundError: No module named 'yaml'

Quick fix: Install PyYAML into the same interpreter that runs the code: python -m pip install pyyaml (inside your venv), or sudo apt install python3-yaml for the system Python on Debian/Ubuntu. Check which Python runs with python -c "import sys; print(sys.executable)".

What it means

import yaml loads a module provided by the PyYAML distribution. The error means Python searched every directory on sys.path and didn't find it. Either PyYAML isn't installed, or it was installed for a different Python than the one running your script.

The import name and the package name are different, which trips people up:

You import You install
yaml pyyaml
dotenv python-dotenv
bs4 beautifulsoup4
cv2 opencv-python
PIL pillow

pip install yaml fails with No matching distribution found; don't install random similarly named packages.

Fix 1: install PyYAML for the interpreter you use

Use python -m pip so pip belongs to the same Python:

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

On Windows use py -m pip install pyyaml. Add it to your dependencies so it doesn't disappear on the next setup:

echo "pyyaml" >> requirements.txt        # or: poetry add pyyaml / uv add pyyaml

Fix 2: you're in the wrong environment

If pip install pyyaml said "Requirement already satisfied" but the import still fails, two Pythons are involved. Compare:

python -c "import sys; print(sys.executable)"
python -m pip --version            # shows which Python pip installs into

Typical mismatches:

Fix 3: system Python on Debian/Ubuntu/Fedora

Recent distributions block pip install into the system Python (externally-managed-environment). Use the distro package:

sudo apt install python3-yaml        # Debian/Ubuntu
sudo dnf install python3-pyyaml      # Fedora/RHEL

Or create a venv for your project:

python3 -m venv .venv && . .venv/bin/activate && pip install pyyaml

Fix 4: Docker images

Install it in the Dockerfile with the image's Python:

FROM python:3.12-slim
RUN pip install --no-cache-dir pyyaml

On Alpine-based images, prebuilt wheels are available for current versions; if pip tries to compile and fails, install py3-yaml with apk add py3-yaml or switch to a -slim image.

Fix 5: a local file named yaml.py

If the error is instead AttributeError: module 'yaml' has no attribute 'safe_load', you have a file called yaml.py (or a folder yaml/) in your project that shadows the real package. Rename it and delete __pycache__.

Using it

Once installed, load files with safe_load, which doesn't execute arbitrary tags:

import yaml

with open("config.yaml") as f:
    config = yaml.safe_load(f)

To check YAML syntax quickly, paste it into the YAML validator.

Last updated 2026-11-11.