Fix: ModuleNotFoundError: No module named 'yaml'

The error you are seeing

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

This error means Python successfully started, found your script, hit import yaml, and could not find a package named yaml on its module search path. The fix is to install pyyaml, which provides the yamlmodule.

Fix 1: pip install pyyaml

The most common case. Note that the PyPI package name and the import name differ:

# The package is called pyyaml, not yaml
pip install pyyaml

# Or, with python3 explicitly
python3 -m pip install pyyaml

pip install yaml will not work - that name does not point to PyYAML on PyPI.

Fix 2: virtual environments

If you use a virtual environment, activate it before installing PyYAML. Otherwise the package goes into the system Python and your venv keeps failing:

# Activate the virtual environment first
source .venv/bin/activate           # macOS / Linux
.\.venv\Scripts\activate           # Windows PowerShell

# Then install
pip install pyyaml

# Verify
python -c "import yaml; print(yaml.__version__)"

The (myenv) prefix in your shell prompt confirms the venv is active. If it is missing, run the activate command again.

Fix 3: Conda environments

Conda manages its own package set. If you mix pip and conda in the same env, you can still hit this error because conda may not recognize pip-installed packages until refreshed:

# Conda environments
conda activate myenv
conda install pyyaml

# Or with conda-forge
conda install -c conda-forge pyyaml

Fix 4: which python is pip targeting?

The trickiest case is when pip says the package is installed but the import still fails. That happens when pip is attached to one Python install while your script runs under a different one. Diagnose like this:

# Confirm which python pip is installing into
python -c "import sys; print(sys.executable)"
which python
which pip

# If they point to different installs, force the same one
python -m pip install pyyaml

On macOS this is especially common because you may have system Python at /usr/bin/python3, Homebrew Python at /opt/homebrew/bin/python3, and a pyenv-managed Python on top. python -m pip install always targets the interpreter you ran python with, so prefer it over a bare pip install.

Fix 5: Docker images

If your container hits the error at runtime, the image was built without PyYAML. Add it to the Dockerfile or requirements.txt and rebuild:

# Add to your Dockerfile
RUN pip install --no-cache-dir pyyaml

# Or in requirements.txt
echo "pyyaml>=6.0" >> requirements.txt
docker build -t myapp .

Should I use ruamel.yaml instead?

ruamel.yaml is a YAML 1.2 compliant alternative to PyYAML. It preserves comments and round-trips cleanly, which PyYAML does not. But its import name is ruamel.yaml, not yaml, so installing it does not fix the original error. If your existing code uses import yaml, install pyyaml. If you are starting fresh and need comment preservation, consider ruamel.yaml instead.

Verify the fix

After installing, confirm everything is wired up correctly:

1. python -c "import yaml; print(yaml.__version__)" prints a version number (e.g. 6.0.1).
2. Re-run your script. The ModuleNotFoundError should be gone.
3. If the error returns later, check that the same venv or Conda env is still active.

Related YAML guides

• YAML validator - check syntax of any YAML file in your browser before Python parses it.
• YAML to JSON converter - useful when comparing PyYAML output to expected JSON.
• Complete YAML guide - YAML syntax, file format, and use cases.