mkcert

name	mkcert
description	Generate locally-trusted TLS certificates for development. Use when you need to understand how mkcert works, need to generate certificates manually outside of ssl-proxy, need to check if mkcert is installed, or are debugging certificate trust issues. Triggers include "mkcert", "local certificate", "self-signed cert", "trusted cert localhost", "local CA".

mkcert

mkcert is a simple tool for making locally-trusted development certificates. It creates a local certificate authority (CA) and installs it into your system trust store.

Check if installed

which mkcert
mkcert --version

Install mkcert

# macOS
brew install mkcert

# macOS/Linux (NSS support for Firefox)
brew install nss  # optional, for Firefox support

# Windows
choco install mkcert

# Direct download
# https://github.com/FiloSottile/mkcert/releases

Install the root CA

Run once per machine. Installs a root CA into your system keychain so all mkcert-generated certs are trusted.

mkcert -install

This requires admin access (macOS Keychain password or sudo on Linux).

Generate a certificate

# For localhost only
mkcert localhost

# For localhost + 127.0.0.1 + ::1 (recommended)
mkcert localhost 127.0.0.1 ::1

# For a custom domain
mkcert myapp.test localhost 127.0.0.1 ::1

# Specify output directory
mkcert -cert-file /path/to/cert.pem -key-file /path/to/key.pem localhost

Output:

• localhost.pem - the certificate
• localhost-key.pem - the private key (keep this secret, 0600 permissions)

View CA location

mkcert -CAROOT
# e.g. /Users/you/Library/Application Support/mkcert

The CA files are at this path:

• rootCA.pem - the CA certificate (safe to share/copy)
• rootCA-key.pem - the CA private key (never share this, 0600 permissions)

Uninstall CA

mkcert -uninstall

Removes the CA from your system trust store. Existing certificates generated from this CA will no longer be trusted.

How it works

1. mkcert -install generates a root CA (rootCA.pem + rootCA-key.pem) and adds rootCA.pem to your system trust store
2. mkcert localhost uses the root CA to sign a new certificate for localhost
3. Because your system trusts the root CA, it also trusts all certs signed by it
4. Browsers trust whatever the OS trust store says, so no security warnings

Key paths by platform

Platform	CA root directory
macOS	~/Library/Application Support/mkcert
Linux	~/.local/share/mkcert
Windows	%LOCALAPPDATA%\mkcert

Security notes

• The root CA private key (rootCA-key.pem) must stay on your machine. Never commit it or share it.
• File permissions on rootCA-key.pem should be 0600.
• mkcert-generated certs are only valid for your local machine because only your machine has the CA in its trust store.
• The CA is NOT trusted by other machines - this is by design.

Troubleshooting

Firefox still shows warning

Install NSS support: brew install nss, then re-run mkcert -install.

"permission denied" when running -install

On Linux, you need sudo: sudo mkcert -install. On macOS, you need your Keychain password.

Certificate not trusted in Chrome on Linux

Chrome on Linux uses the NSS database. Install NSS tools: sudo apt install libnss3-tools, then mkcert -install again.