Install & Compatibility
Where this runs
tested against v3.1.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.95 runs
installs and imports cleanly · install 0.0s · import 0.150s · 18.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.138s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
IMAPClient
✓ from imapclient import IMAPClient
This quickstart connects to an IMAP server, logs in using credentials from environment variables, selects the 'INBOX' folder, and fetches the subjects of the first few messages. It demonstrates basic connection, authentication, folder selection, and message fetching. Ensure `IMAP_HOST`, `IMAP_USERNAME`, and `IMAP_PASSWORD` environment variables are set.
import os
from imapclient import IMAPClient
# Environment variables for credentials
IMAP_HOST = os.environ.get('IMAP_HOST', 'imap.example.com')
IMAP_USERNAME = os.environ.get('IMAP_USERNAME', 'your_username')
IMAP_PASSWORD = os.environ.get('IMAP_PASSWORD', 'your_password')
try:
# Connect to the IMAP server using a context manager for automatic logout
with IMAPClient(IMAP_HOST, ssl=True) as client:
client.login(IMAP_USERNAME, IMAP_PASSWORD)
print(f"Successfully logged in to {IMAP_HOST} as {IMAP_USERNAME}")
# Select the INBOX folder
select_info = client.select_folder('INBOX')
print(f"Selected INBOX: {select_info[b'EXISTS']} messages")
# Search for all messages
messages = client.search(['ALL'])
print(f"Found {len(messages)} messages.")
if messages:
# Fetch subjects of the first 5 messages (or fewer if not enough)
fetch_uids = messages[:5]
response = client.fetch(fetch_uids, ['BODY.PEEK[HEADER.FIELDS (SUBJECT)]'])
print("\n--- Subjects of first messages ---")
for uid, data in response.items():
subject_bytes = data[b'BODY[HEADER.FIELDS (SUBJECT)]']
try:
# Decode subject, handling potential encoding issues
subject = subject_bytes.decode('utf-8', errors='ignore').strip()
print(f"UID {uid}: {subject}")
except UnicodeDecodeError:
print(f"UID {uid}: Subject decoding failed")
else:
print("No messages in INBOX.")
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
breakingVersion 3.0.0 removed official support for Python 2.x. Applications targeting Python 2 must remain on `imapclient < 3.0.0`.fixUpgrade to Python 3.8+ and `imapclient >= 3.0.0`. If Python 2 is required, use `imapclient < 3.0.0`.
affects: <3.0.0
breakingVersion 3.0.0 also removed support for Python 3.4, 3.5, and 3.6. The current officially supported Python versions are 3.8 through 3.13.fixEnsure your project runs on Python 3.8 or newer.
affects: <3.0.0
gotchaUsers running Python 3.14+ might experience compatibility issues with `IMAP4_TLS` if using `imapclient` versions older than 3.1.0.fixUpgrade `imapclient` to version 3.1.0 or newer to ensure full compatibility with Python 3.14+.
affects: <3.1.0 (when used with Python 3.14+)
gotchaSince version 1.0, IMAPClient enables strict TLS certificate verification by default. Connections to servers with self-signed or invalid certificates may fail.fixIf connecting to a server with a self-signed certificate (not recommended for production without proper CA setup), you may need to configure the `ssl_context` to disable hostname checking or verification. For example:
```python
import ssl
context = ssl.create_default_context()
context.check_hostname = False
context.verify_mode = ssl.CERT_NONE
client = IMAPClient(host, ssl_context=context)
```
affects: >=1.0.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'imapclient'
The `imapclient` package is not installed in the Python environment you are using.
fixInstall the package using pip: `pip install imapclient`
imapclient.exceptions.LoginError: b'LOGIN failed.'
The IMAP server rejected the login attempt, usually due to incorrect username/password, disabled IMAP access, or requiring an app-specific password/OAuth for accounts with 2-Factor Authentication (2FA) enabled.
fixDouble-check credentials, ensure IMAP is enabled for the account, and if 2FA is active, generate and use an app-specific password or configure OAuth for authentication.
ssl.SSLError: CERTIFICATE_VERIFY_FAILED
The Python environment cannot verify the SSL certificate presented by the IMAP server, often due to missing or outdated root certificates on the system (common on macOS) or self-signed certificates.
fixOn macOS, run `/Applications/Python \<version\>/Install Certificates.command`. Alternatively, use the `certifi` package or provide a custom `ssl_context` to `IMAPClient` to handle certificates. For testing, you can pass `ssl_context=ssl._create_unverified_context()` (not recommended for production).
AttributeError: property 'file' of 'IMAP4_TLS' object has no setter
This error occurs with Python 3.14 due to a change in the standard library's `imaplib.IMAP4.file` attribute, which became a read-only property, breaking `imapclient`'s internal handling.
fixThis is a compatibility issue with Python 3.14 that requires an update to `imapclient`. Check for a newer version of `imapclient` or use a supported Python version (e.g., Python 3.13 or earlier) if an update is not yet available.
UnicodeDecodeError: 'utf-8' codec can't decode byte 0x... in position ...: invalid start byte
This error happens when `imapclient` attempts to decode email content as UTF-8, but the email actually contains bytes encoded in a different character set.
fixWhen fetching the raw email, use `email.message_from_bytes()` from Python's `email` module to robustly parse the message, which automatically handles different encodings. For example: `email.message_from_bytes(message_data[b'RFC822'], policy=policy.default)`
Upgrade
Version history
3.1.0latest on PyPI · released Jan 17, 2026
Audit
Dependencies
No dependency data recorded yet.