Install & Compatibility
Where this runs
tested against v6.6.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.914s · 38.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.0s · import 0.846s · 38MB
36MB installed
● package 36MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
HttpNtlmAuth
✓ from requests_ntlm2 import HttpNtlmAuth
✗ from requests_ntlm import HttpNtlmAuth
requests-ntlm2 is a fork of requests-ntlm; ensure you import from the correct package.
HttpNtlmAdapter
✓ from requests_ntlm2 import HttpNtlmAdapter
Required for NTLM authentication with HTTP CONNECT proxies.
NtlmCompatibility
✓ from requests_ntlm2 import NtlmCompatibility
Used to specify NTLM compatibility levels (e.g., NTLMv2, LM_AND_NTLMv1_WITH_ESS).
This quickstart demonstrates basic NTLM authentication with `requests-ntlm2` using `HttpNtlmAuth`. It also shows the recommended approach of using it with a `requests.Session` for improved efficiency and connection pooling. Replace placeholder environment variables with your actual NTLM credentials and target URL.
import requests
from requests_ntlm2 import HttpNtlmAuth
import os
# Replace with your NTLM domain, username, and password
NTLM_USERNAME = os.environ.get('NTLM_USERNAME', 'DOMAIN\\username')
NTLM_PASSWORD = os.environ.get('NTLM_PASSWORD', 'password')
TARGET_URL = os.environ.get('TARGET_URL', 'http://ntlm_protected_site.com')
# Basic NTLM authentication
try:
auth = HttpNtlmAuth(NTLM_USERNAME, NTLM_PASSWORD)
response = requests.get(TARGET_URL, auth=auth)
response.raise_for_status() # Raise an exception for bad status codes
print(f"Successfully authenticated to {TARGET_URL}. Status: {response.status_code}")
# print(response.text[:200]) # Print first 200 characters of content
except requests.exceptions.RequestException as e:
print(f"Error during basic NTLM authentication: {e}")
# Using with a Session for efficiency (recommended for multiple requests)
from requests import Session
session = Session()
session.auth = HttpNtlmAuth(NTLM_USERNAME, NTLM_PASSWORD)
try:
session_response = session.get(TARGET_URL)
session_response.raise_for_status()
print(f"Successfully authenticated with session to {TARGET_URL}. Status: {session_response.status_code}")
except requests.exceptions.RequestException as e:
print(f"Error during session NTLM authentication: {e}")
Errors
Common errors & fixes
ConnectionError: HTTPSConnectionPool(host='...', port=443): Max retries exceeded with url: / (Caused by ProxyError('Cannot connect to proxy.', error('Tunnel connection failed: 407 Proxy Authentication Required',)))
This error typically indicates that your HTTPS proxy requires NTLM authentication for the CONNECT method, but `requests-ntlm2` is not configured to handle it at the `httplib` level.
fixUse `HttpNtlmAdapter` with `requests.Session` and mount it to handle the proxy authentication: `session = requests.Session(); session.mount('https://', HttpNtlmAdapter(auth=HttpNtlmAuth(username, password)))`. ImportError: No module named requests_ntlm2
The `requests-ntlm2` package is either not installed, or Python is trying to import it from a conflicting directory (e.g., a local file named `requests_ntlm2.py`).
fixEnsure `pip install requests-ntlm2` completed successfully. Check your working directory for any files that might shadow the installed package. If using a virtual environment, activate it.
requests.exceptions.HTTPError: 401 Client Error: Unauthorized for url: ...
This usually means the NTLM credentials provided are incorrect, or the server's NTLM configuration does not accept the client's authentication attempt (e.g., unsupported NTLM compatibility level).
fixVerify the username (including domain, e.g., `DOMAIN\username`) and password. Experiment with different `NtlmCompatibility` levels if the credentials are known to be correct but still failing.
Upgrade
Version history
6.6.0latest on PyPI · released May 28, 2025
Audit
Dependencies
requestsrequiredCore HTTP library that requests-ntlm2 extends for NTLM authentication.
pyspnegorequiredProvides underlying SPNEGO/NTLM protocol support.