Docker Compose for Mailpit: catch test emails on localhost

Run a fake mail server on your computer, so test emails from your app show up in a web page instead of being sent.

For Docker with the Compose plugin (Docker Desktop, or Docker Engine 20.10 or newer).

Mailpit catches every email your app sends during development and shows it in a web inbox, so nothing reaches real people. Save this file, run one command, and point your app's mail settings at port 1025.

Create your config file

Type your own values. The file below updates as you type, and nothing you type leaves your browser.

services:
  mailpit:
    image: axllent/mailpit
    container_name: mailpit
    restart: unless-stopped
    ports:
      - "8025:8025"
      - "1025:1025"

How this setup works

Step-by-step setup

1. Save the file above as docker-compose.yml.
2. Start it: docker compose up -d.
3. Open http://localhost:8025 to see the empty inbox.
4. In your app set the mail host to localhost, the port to 1025, and leave the username, password and encryption empty.
5. Send a test email from your app. It appears in the inbox within a second.

What the important lines mean

• "8025:8025" opens the web inbox on your computer's port 8025.
• "1025:1025" opens the mail port your app sends to.
• MP_DATABASE saves mail in a file inside a volume, so it survives a restart.
• Without that option, emails are kept in memory and disappear when the container stops.

Common errors and how to fix them

Bind for 0.0.0.0 failed: port is already allocated

Another program uses that port, such as an older mail tool. Change the left number of the port line, or stop the other program.

Connection refused on the SMTP port

The container is not running, or your app runs inside another container where localhost is itself. Use the service name mailpit as the host when both are in the same Compose file.

Emails do not appear in the inbox

Your app is not using SMTP, or its mail setting points elsewhere. Check the host and port, and turn encryption and authentication off.

SSL or TLS error from the app

Mailpit accepts plain SMTP by default. Set the encryption option in your app to none.

Frequently asked questions

Is Mailpit safe to use?

Yes for development. It never sends mail onward, so test emails cannot reach real addresses. Do not expose its ports to the internet.

What are the usual app settings?

Host localhost, port 1025, no username, no password, no encryption. In Laravel set MAIL_HOST and MAIL_PORT. In WordPress use an SMTP plugin with the same values.

Is this the same as MailHog?

They do the same job and use the same ports. Mailpit is actively developed, while MailHog has not had updates for years.

Written for: Docker Compose v2 · Updated 2026-10-11

Free tools that help

• Common ports listSearch a list of common TCP and UDP port numbers: SSH 22, HTTP 80, HTTPS 443, MySQL 3306, PostgreSQL 5432 and more, with dev server ports.

Fix a problem with this setup

• Docker port already allocatedFix "port is already allocated" in Docker and Docker Compose: find the container or program that holds the port and free it.
• Docker container cannot reach localhostFix "connection refused" when an app in Docker calls localhost: use host.docker.internal, a Compose service name or host networking.

More container configs

• Kubernetes Deployment and ServiceA Deployment and Service YAML for your container image, with replicas, port, resource limits and health checks.
• Docker Compose for MySQL and phpMyAdminRun MySQL and the phpMyAdmin web page on your computer with one docker compose command.
• Docker Compose for PostgreSQL and pgAdminRun PostgreSQL and the pgAdmin web page on your computer with one docker compose command.
• docker-compose for MongoDBRun a local MongoDB database with a password that keeps its data.
• docker-compose for PostgreSQLRun a local PostgreSQL database that keeps its data.
• docker-compose for MySQLRun a local MySQL database in Docker with your own user, password and port, and keep the data between restarts.

See all 41 config generators