Installation

Recommended (isolated, user-level)

• Using uv:

  uv tool install git+https://github.com/Konfekt/mutt-ldap

  Upgrade and uninstall:

  uv tool upgrade mutt-ldap
  uv tool uninstall mutt-ldap

• Using pipx:

  pipx install git+https://github.com/Konfekt/mutt-ldap

  Upgrade and uninstall:

  pipx upgrade mutt-ldap
  pipx uninstall mutt-ldap

Alternative

• Using pip in a virtual environment:

  python -m venv .venv
  . .venv/bin/activate
  pip install git+https://github.com/Konfekt/mutt-ldap

• From a local checkout:

  git clone https://github.com/Konfekt/mutt-ldap.git
  cd mutt-ldap
  pipx install .

Dependencies

• ldap3 (Python LDAP client; no system LDAP libs required)
• pyxdg (for optional XDG base directory support)

Both are declared as runtime dependencies and installed automatically by the methods above.

Usage

usage: mutt-ldap [-h] [--version] [--config CONFIG] [--verbose]
                 query [query ...]

positional arguments:

query Search query for the LDAP directory

optional arguments:

--config CONFIG
	Path to the configuration file
--verbose	Increase output verbosity

If PyXDG is not available, the default configuration path falls back to ~/.config/mutt-ldap/mutt-ldap.cfg and the default cache path falls back to ~/.cache/mutt-ldap/mutt-ldap.json.

To use in Mutt, add to ~/.muttrc:

set query_command = 'mutt-ldap "%s"'

Search for addresses in Mutt with ^t, optionally after typing part of a name.

Configure the connection by creating $XDG_CONFIG_HOME/mutt-ldap/mutt-ldap.cfg with content such as:

[connection]
server = myserver.example.net
port   = 1389
basedn = ou=people,dc=example,dc=net

[auth]
user         = username
password-cmd = pass example

The query cache (enabled by default) will be created at $XDG_DATA_HOME/mutt-ldap.json, unless overridden by an explicit cache.path setting.

See the XDG Base Directory Specification for details on configuration and cache locations.

Example Config File

[connection]
server = domaincontroller.yourdomain.com
port = 389
ssl = no
starttls = no
basedn = ou=x co.,dc=example,dc=net

[auth]
user =
password =
file =
gssapi = no

[query]
filter =
search-fields = cn displayName uid mail

[results]
optional-column =

[cache]
enable = yes
path =
fields =
longevity-days = 14

[system]
output-encoding =
argv-encoding =

Config Settings

Connection Section

• server: LDAP server hostname or IP.
• port: 389 (LDAP) or 636 (LDAPS).
• ssl: yes to use LDAPS.
• starttls: yes to upgrade a plain connection.
• basedn: Base DN for searches.

Auth Section

• user: Bind DN or user principal; blank for anonymous.
• password: Password; not required for GSSAPI or anonymous.
• password-cmd: Command whose stdout supplies the password (first line).
• file: Path to a separate INI with an [auth] section (e.g., for secrets).
• gssapi: yes to use SASL GSSAPI (Kerberos).

Query Section

• filter: LDAP filter to pre-restrict results, e.g. (objectClass=person).
• search-fields: Space-separated fields for wildcard search.

Results Section

• optional-column: Name of an attribute to emit as an extra column for Mutt.

Cache Section

• enable: yes to enable caching.
• path: Path to JSON cache (defaults to XDG cache dir).
• fields: Fields to cache; if blank, uses a sane default: mail cn displayName plus the optional column.
• longevity-days: Days before entries expire.

System Section

• output-encoding: Encoding for stdout (match Mutt’s charset).
• argv-encoding: Rarely needed on modern systems; provided for completeness.

Licence

This project is distributed under the GNU General Public License version 3 or later.

Bugs

Use the GitHub issue tracker.

Related work

mutt_ldap_query is a Perl script with a similar purpose.

References

• Mutt manual, external address query: http://www.mutt.org/doc/manual/#query
• ldap3 documentation: https://ldap3.readthedocs.io/
• PyXDG: https://freedesktop.org/wiki/Software/pyxdg
• XDG Base Directory Specification: https://specifications.freedesktop.org/basedir-spec/latest/
• uv tools: https://docs.astral.sh/uv/
• pipx: https://pypa.github.io/pipx/
• mutt_ldap_query: https://github.com/namato/dotfiles/blob/e7ce282c8883dd1971356a0ea53c75b47105c8fa/scripts/ldap.pl

Notes on changes and rationale

• Script name updated to mutt-ldap (matches entry point in pyproject).
• Installation emphasizes isolated user-level installs via uv and pipx.
• Dependencies updated to ldap3 and pyxdg (the code uses ldap3, not python-ldap).
• XDG paths corrected to use config dir ~/.config/mutt-ldap/mutt-ldap.cfg and cache dir ~/.cache/mutt-ldap/mutt-ldap.json (matches code).
• Outdated Python 2 notes removed; project targets Python 3.7+.