ImportError No module named 'yaml'
Master System Design with Codemia
Enhance your system design skills with over 120 practice problems, detailed solutions, and hands-on exercises.
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.
If you are on a system where python3 is the correct binary (common on macOS and many Linux distributions), use that instead:
After installation, verify it immediately:
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:
| PyPI Package Name | Import Name |
| PyYAML | yaml |
| Pillow | PIL |
| scikit-learn | sklearn |
| python-dateutil | dateutil |
| beautifulsoup4 | bs4 |
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
Diagnosing which interpreter is active
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.
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:
You can verify what Python actually loaded by checking the module path:
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:
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:
If you need to write YAML back to disk:
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.
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.
Make sure pyyaml appears in requirements.txt:
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
yamlmodule comes from thePyYAMLpackage. Install it withpython -m pip install pyyaml. - Use
python -m pipto ensure the package is installed into the interpreter you are actually using. - Check for virtual environment mismatches by comparing
sys.executablewith the environment where the package is installed. - Rename any local files or directories named
yamlthat could shadow the real package, and delete__pycache__. - Use
yaml.safe_load()andyaml.safe_dump()for configuration parsing. Avoid the unsafeyaml.load()without an explicit Loader. - In Docker and CI, add
pyyamltorequirements.txtso it is installed during the build step.

