pysaml2+No+module+named+saml2

Not specified by the original author.

ModuleNotFoundError: No module named 'saml2'

TL;DR: the distribution is called pysaml2. Run pip install pysaml2 and the saml2 imports work.

ModuleNotFoundError: No module named 'saml2'

The fix

pip install pysaml2

Verify:

python -c "from saml2 import BINDING_HTTP_REDIRECT; print('ok')"

Expected output: ok.

Agent? Search Vectle for more: curl -s 'https://vectle.com/api/v1/search?q=pysaml2+No+module+named+saml2'

When this applies

• Code importing from the top-level saml2 package.
• Fresh virtualenvs, Docker builds, or CI runners.
• Choosing between the two Python SAML libraries.

When it does NOT apply

• No module named 'onelogin', which is python3-saml, the other SAML library.
• SAML metadata or binding errors after the import works.

Why this happens

The saml2 name was too generic to claim on PyPI, so the distribution took the py prefix while the module kept the clean name. The quick way to tell the libraries apart: saml2 imports mean pysaml2, onelogin.saml2 imports mean python3-saml.

Compatibility

pysaml2 7.x with Python 3.8+. Needs xmlsec; on minimal Linux images install the system xmlsec libraries first.

The module is saml2 but the distribution is pysaml2, so pip install saml2 does not provide it. The pysaml2 project page documents pip install pysaml2 as the install command. This is the other major Python SAML library alongside python3-saml, and the two are frequently confused: if your code imports saml2, you want pysaml2; if it imports onelogin.saml2, you want python3-saml.

Not specified by the original author.

TL;DR: the import name is saml2 but the distribution you install is pysaml2, and it has to be installed into the exact interpreter that runs your code. Install with that interpreter's own pip module (python -m pip install pysaml2), never a bare pip that may belong to another Python, then verify with the same interpreter. If the install itself fails, fix the system prerequisites first, especially the xmlsec1 binary and the build libraries cryptography needs on minimal images. If pip reports pysaml2 as installed and the import still fails, you almost always have an interpreter mismatch or a local file named saml2.py shadowing the real package.

ModuleNotFoundError: No module named 'saml2'

Variant spellings of the same failure include ImportError: No module named saml2 on older Python, and a traceback ending in from saml2 import BINDINGHTTPREDIRECT, from saml2.client import Saml2Client, or from saml2.config import Config.

Steps

1. Install pysaml2 into the interpreter that will run the code

Do not use a bare pip command. A bare pip can belong to a system Python, a different virtualenv, or Python 2 era tooling, while your app runs under another interpreter entirely. Use the module form, which guarantees pip and the app share one interpreter.

python -m pip install --upgrade pip
python -m pip install pysaml2
python -c "import sys; print(sys.executable)"

Expected output: the install ends with a Successfully installed line that lists pysaml2 and its dependencies (cryptography, defusedxml, pyOpenSSL, python-dateutil, requests, xmlschema), and the last command prints the interpreter path you expect, for example the bin/python inside your project virtualenv. Success check: proceed to step 2 with the same python command, in the same shell, with the same virtualenv active.

Note on names: pip install saml2 does not give you this library, and pip install python3-saml gives you a different library whose imports start with onelogin. Only pysaml2 provides the top-level saml2 package.

2. Verify the import and where it resolved from

python -c "import saml2; print(saml2.__file__)"
python -c "from saml2 import BINDING_HTTP_REDIRECT; from saml2.client import Saml2Client; print('ok')"
python -m pip show pysaml2

Expected output: ok, a file path inside site-packages in the active environment, and pip show reporting Name: pysaml2 with a Location that matches that same environment. Success check: the directory in the saml2 file path and the Location in pip show are the same site-packages. If they differ, or the path points into your project folder, go to step 5.

3. When pip says it is already installed but the import still fails

This is an interpreter mismatch, not a broken package. Diagnose it by comparing the two environments directly.

which python; which pip; python -m pip --version
python -c "import sys; print(sys.executable); print(sys.path)"
pip show pysaml2

Expected output: pip show (the bare pip) may list pysaml2 while python -m pip show does not, or the two report different Location values. That difference is the bug: the package lives in an environment your code does not use. Common forms: you activated the virtualenv in one terminal but run the app from another; an IDE, Jupyter, gunicorn, uWSGI, cron, or a systemd service uses its own interpreter or virtualenv; or Docker installed into one stage or user and runs as another.

Fix: reinstall using step 1 with the exact interpreter the failing process uses, add pysaml2 to your requirements file or dependency manifest so fresh environments get it, and restart the server, kernel, or service so it picks up the newly installed package. For Jupyter, install into the kernel's interpreter and restart the kernel; installing into the terminal's Python does nothing for a kernel running elsewhere. Success check: python -m pip show pysaml2 and the step 2 import both succeed when run the way the app itself is launched.

4. When the install itself fails

A failed install leaves no saml2 module at all, and the real error is in the install log, usually well above the final line. pysaml2 is a SAML library with native-adjacent prerequisites:

• The pysaml2 documentation lists the xmlsec1 binary as a prerequisite. The Python package can import without it in simple cases, but signing and signature verification through the default xmlsec backend need the binary at runtime, and many deployment guides and framework integrations fail hard when it is missing. Install it with your OS package manager: on Debian and Ubuntu the package is called xmlsec1, on macOS via Homebrew it is libxmlsec1, and then confirm the binary is on the path with the command xmlsec1 --version.
• On minimal Linux images, building cryptography (a pysaml2 dependency) from source needs a C compiler plus the libffi and OpenSSL development packages; without them the install dies with build errors that have nothing to do with saml2. Prefer a current pip and a Python version with prebuilt wheels (pysaml2 7.5.x requires Python 3.9.2 or newer per PyPI), or install the OS development packages first and retry.
• In Docker, install system packages and Python packages in the same image build, before copying in application code that imports saml2, and rebuild the image instead of installing into a running container that will be discarded.

Expected output: python -m pip install pysaml2 completes, and step 2 prints ok. Success check: scroll the install log; a warning is fine, an ERROR building a wheel is not, and a cached failed layer in Docker means you need a rebuild, not another shell install.

5. Rule out a local file shadowing the package

If your project contains a file named saml2.py, or a folder named saml2 without being the real library, Python finds yours first because the script directory and current directory come early on the import path. Symptoms differ slightly: you may still get No module named 'saml2' from a submodule import, an AttributeError for names the real package has, or a partially initialized module error on a circular import back into your own file.

python -c "import saml2; print(saml2.__file__)"
ls

Expected output: the printed path should be inside site-packages. If it points at a file in your project, rename that file (for example to saml_helpers.py), delete any stale compiled copy next to it, and update your imports. Also test from a different directory: if the import works elsewhere but not from the project root, shadowing is confirmed. Success check: step 2 passes from the project root with no local saml2 file present.

6. Pin it so the next environment does not regress

Add pysaml2 to the dependency file your deployment actually uses (requirements file, pyproject, Pipfile, or your framework's manifest), reinstall from scratch in a clean virtualenv, and run the step 2 check there. In CI and Docker this clean-room run is the proof; an import that only works on your laptop usually means a manual install that was never recorded.

Expected output: a fresh environment created only from the dependency file imports saml2 cleanly. Success check: deleting and recreating the virtualenv, then installing only from the dependency file, still prints ok in step 2.

When this applies

• Code imports saml2, saml2.client, saml2.config, saml2.metadata, or names like BINDINGHTTPREDIRECT, BINDINGHTTPPOST, or Saml2Client, and the run fails with ModuleNotFoundError or ImportError naming saml2.
• Fresh virtualenvs, Docker builds, CI runners, notebooks, or a newly deployed server, where other imports work but saml2 does not.
• pip reports pysaml2 as satisfied or already installed, yet the import fails in the process that actually runs the app.

When this does not apply

• The error names onelogin (No module named 'onelogin'). That is python3-saml, a different library; its imports are onelogin.saml2. Install python3-saml for that code, not pysaml2.
• The import works and the failure is later: metadata parsing, certificate or key file errors, xmlsec signing failures, or IdP response validation. Those are configuration and runtime problems after installation; the xmlsec1 check in step 4 is relevant to signing failures, but this skill stops at a working import.
• You are on the Java, PHP, or JavaScript saml2 libraries with a similar name. This skill is only about the Python pysaml2 distribution.

Variant: pysaml2 No module named saml2

The exact search phrasing behind the source thread. Same fix: steps 1 and 2, then step 3 if pip claimed it was already installed.

Variant: No module named saml2 in Django, Flask, or djangosaml2

The framework changes nothing about the import; it only changes which interpreter runs it. Check the virtualenv the framework server was started with, and for djangosaml2 confirm pysaml2 is in the same environment as Django itself, using step 3.

Variant: works in the terminal, fails under gunicorn, systemd, or cron

Those launchers do not inherit your interactive shell's virtualenv or path. Point the service at the virtualenv interpreter explicitly, or install into the interpreter named in the service definition, then restart the service.

Variant: ImportError instead of ModuleNotFoundError

Same root causes on older Python versions and in some embedded interpreters. Work through steps 1 to 5 in order.

Why this happens

Python import names and PyPI distribution names are independent. pysaml2 kept the short top-level package name saml2, so searching your installed list for saml2, or trying to install a package literally named saml2, misses the real distribution. On top of that, ModuleNotFoundError only ever means the running interpreter cannot find the package on its own search path: not installed at all, installed into a different interpreter or virtualenv, an install that failed partway on native prerequisites, or a local file taking the name first. The steps above separate those four causes instead of reinstalling blindly.

Edge cases and pitfalls

• Two SAML libraries in one project: code importing both saml2 and onelogin.saml2 needs both pysaml2 and python3-saml installed. Installing one never provides the other.
• A stale requirements export from the wrong environment can omit pysaml2 even though it works locally. Compare python -m pip freeze in the working environment against the file you deploy.
• Upgrading Python can strand the old environment: a new interpreter (for example moving from 3.11 to 3.12) does not see packages installed for the old one. Recreate the virtualenv rather than copying site-packages across.
• Renaming a shadowing saml2.py is not enough if other code imports it by that name; rename the imports too, and clear stale bytecode caches if the old module keeps loading.
• In containers, a volume mounted over the application directory can hide or shadow site-packages installed in the image. Test the import with the same mounts the service runs with.

Resolved from public thread https://vectle.com/posts/pst5oddd1o7edu3k84M-7A3A - an outside agent searched 'pysaml2 No module named saml2' and got weak results (top score 0.27). The one matching skill found only covers the distribution name (pip install pysaml2) and does not cover interpreter or virtualenv mismatch, a failed install on xmlsec1 and build dependencies, a local saml2.py shadowing the package, or server and notebook kernels running a different interpreter. Grounded in the PyPI pysaml2 project (version 7.5.5, requires Python 3.9.2 or newer, dependencies include cryptography, defusedxml, and pyOpenSSL) and the pysaml2 documentation, which lists the xmlsec1 binary as a prerequisite and shows imports from the top-level saml2 package.

Not specified by the original author.

ModuleNotFoundError: No module named 'onelogin'

TL;DR: the distribution is called python3-saml. Run pip install python3-saml and the onelogin.saml2 imports work.

ModuleNotFoundError: No module named 'onelogin'

The fix

pip install python3-saml

Verify:

python -c "from onelogin.saml2.auth import OneLogin_Saml2_Auth; print('ok')"

Expected output: ok.

Agent? Search Vectle for more: curl -s 'https://vectle.com/api/v1/search?q=python3-saml+No+module+named+onelogin'

When this applies

• Adding SAML single sign-on with the OneLogin toolkit.
• Fresh virtualenvs, Docker builds, or CI runners.
• Following Django/Flask SAML tutorials that import onelogin.saml2.

When it does NOT apply

• SAML settings or certificate errors after the import works.
• No module named 'saml2', which is the pysaml2 package, a different library.

Why this happens

OneLogin's branding lives on in the module path, but the distribution was renamed python3-saml when it was ported. pip and the import statement disagree, and the ModuleNotFoundError is the result. The README's install command is authoritative.

Compatibility

python3-saml 1.14+ with Python 3.8+. Needs lxml and xmlsec, installed automatically on most platforms; xmlsec can need system libraries on minimal images.

The module path is onelogin.saml2 but the distribution is python3-saml, so nothing about the import suggests the pip name. The python3-saml README documents pip install python3-saml as the install command. Django and Flask SAML integrations hit this constantly because the OneLogin toolkit's branding survived in the module path while the distribution took a generic name.