mkcert

A simple zero-config tool to make locally-trusted development certificates

Description

mkcert is a simple tool written in Go that allows you to create locally-trusted development certificates without any configuration. It automatically creates and installs a local root CA in the system trust store and generates locally-trusted certificates.

Examples

Generate locally-trusted certificates and use them with ncat:

❯ mkcert -install
The local CA is already installed in the system trust store! 👍
The local CA is already installed in the Firefox and/or Chrome/Chromium trust store! 👍

❯ mkcert example.com "*.example.com" example.test localhost 127.0.0.1 ::1

Created a new certificate valid for the following names 📜
 - "example.com"
 - "*.example.com"
 - "example.test"
 - "localhost"
 - "127.0.0.1"
 - "::1"

The certificate is at "./example.com+5.pem" and the key at "./example.com+5-key.pem" ✅
It will expire on 30 January 2025 🗓

❯ ncat -lvp 1589 --ssl-key example.com+5-key.pem --ssl-cert example.com+5.pem 
Ncat: Version 7.92 ( https://nmap.org/ncat )
Ncat: Listening on :::1589
Ncat: Listening on 0.0.0.0:1589

Installation

Warning: The rootCA-key.pem file generated by mkcert provides full power to intercept secure requests on your machine. Do not share it.

macOS

$ brew install mkcert
$ brew install nss # If you use Firefox

Linux

On Linux, first install certutil:

$ sudo apt install libnss3-tools
# or
$ sudo yum install nss-tools
# or
$ sudo pacman -S nss

Then install via Homebrew:

$ brew install mkcert

Alternatively, build from source (requires Go 1.13+):

git clone https://github.com/FiloSottile/mkcert && cd mkcert
go build -ldflags "-X main.Version=$(git describe --tags)"

Or use pre-built binaries from the releases page.

Windows

Using Chocolatey:

$ choco install mkcert

Or using Scoop:

$ scoop bucket add extras
$ scoop install mkcert

Supported Root Stores

mkcert supports the following root stores:

• macOS system store
• Windows system store
• Linux distributions (via update-ca-trust, update-ca-certificates, or trust)
• Firefox (macOS and Linux only)
• Chrome and Chromium
• Java (when JAVA_HOME is set)

Advanced Topics

Options

-cert-file FILE, -key-file FILE, -p12-file FILE
    # Custom output paths.
-client # Generate a certificate for client authentication.
-ecdsa  # Use an ECDSA key for the certificate.
-pkcs12 # Generate a ".p12" PKCS #12 file.
-csr CSR # Generate a certificate based on a CSR.

Example with Custom Files

mkcert -key-file key.pem -cert-file cert.pem example.com *.example.com

S/MIME

To generate an S/MIME certificate:

mkcert filippo@example.com

Mobile Devices

To make mobile devices trust the certificates, install the root CA (rootCA.pem). You can find its location using:

mkcert -CAROOT

Using with Node.js

Node.js does not use the system root store. You must set the NODE_EXTRA_CA_CERTS environment variable:

export NODE_EXTRA_CA_CERTS="$(mkcert -CAROOT)/rootCA.pem"

Note on Usage

mkcert is intended for development purposes only and should not be used in production environments. Never share or export the rootCA-key.pem file.