Skip to content

README.md

Latest commit

 

History

History
259 lines (177 loc) · 9.82 KB

README.md

File metadata and controls

259 lines (177 loc) · 9.82 KB
Raw

mkcert

mkcert is a simple tool for making locally-trusted development certificates. It requires no configuration.

$ mkcert -install
Created a new local CA 💥
The local CA is now installed in the system 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" ✅

Chrome and Firefox screenshot

Using certificates from real certificate authorities (CAs) for development can be dangerous or impossible (for hosts like example.test, localhost or 127.0.0.1), but self-signed certificates cause trust errors. Managing your own CA is the best solution, but usually involves arcane commands, specialized knowledge and manual steps.

mkcert automatically creates and installs a local CA in the system root store, and generates locally-trusted certificates. mkcert does not automatically configure servers to use the certificates, though, that's up to you.

Installation

Warning

The rootCA-key.pem file that mkcert automatically generates gives complete power to intercept secure requests from your machine. Do not share it.

macOS

On macOS, use Homebrew

brew install mkcert

or MacPorts.

sudo port selfupdate
sudo port install mkcert

or Flox.

flox install mkcert

Linux

Package provided by Linux distribuitions

Various Linux distributions have packaged mkcert, check the following table if your Linux distribution provides a package and how it can be installed.

Linux distribution Package How to install
Alpine mkcert sudo apk add mkcert
Alt mkcert sudo apt-get install mkcert
Arch mkcert sudo pacman -Syu mkcert
Debian mkcert sudo apt-get install mkcert
Fedora mkcert sudo dnf install -y mkcert
Gentoo app-misc/mkcert sudo emerge app-misc/mkcert
Homebrew mkcert sudo brew install mkcert
Kali mkcert sudo apt install mkcert
LiGurOS app-misc/mkcert sudo emerge app-misc/mkcert
Nix mkcert sudo nix-shell -p mkcert
OpenSUSE mkcert sudo zypper install mkcert
Parabola mkcert sudo pacman -Syu mkcert
PureOS mkcert sudo apt-get install mkcert
T2 SDE mkcert sudo apt-get install mkcert
Trisquel mkcert sudo apt-get install mkcert
Ubuntu mkcert sudo apt-get install mkcert

Manually

On Linux, first install certutil.

sudo apt install libnss3-tools
    -or-
sudo yum install nss-tools
    -or-
sudo pacman -S nss
    -or-
sudo zypper install mozilla-nss-tools

Then you can install using Homebrew on Linux

brew install mkcert

or build from source (requires Go 1.26+)

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

or use the pre-built binaries.

curl -JLO "https://dl.filippo.io/mkcert/latest?for=linux/amd64"
chmod +x mkcert-v*-linux-amd64
sudo cp mkcert-v*-linux-amd64 /usr/local/bin/mkcert

For Flox users, mkcert can be installed into a Flox environment.

flox install mkcert

If you prefer building and running mkcert in a Docker container

docker build . -t mkcert
docker run -it --rm --user $UID -v $PWD:/tmp/certs mkcert localhost 127.0.0.1 ::1

Windows

On Windows, use Chocolatey

choco install mkcert

or use Scoop

scoop bucket add extras
scoop install mkcert

or use Winget

winget install -e --id FiloSottile.mkcert

or build from source (requires Go 1.26+), or use the pre-built binaries.

If you're running into permission problems try running mkcert as an Administrator.

Supported root stores

mkcert supports the following root stores:

  • macOS system store
  • Windows system store
  • Linux variants that provide either
    • update-ca-trust (Fedora, RHEL, CentOS) or
    • update-ca-certificates (Ubuntu, Debian, OpenSUSE, SLES) or
    • trust (Arch)
  • Firefox (macOS and Linux only)
  • Chrome and Chromium
  • Java (when JAVA_HOME is set)

To only install the local root CA into a subset of them, you can set the TRUST_STORES environment variable to a comma-separated list. Options are: "system", "java", and "nss" (includes Firefox).

Note that Firefox version 120 and later trusts certificates added to the system root store by default on macOS and Windows, so installing to the "nss" root store should be unnecessary on these platforms.

Manually-supported root stores

  • NixOS Linux: Add to configuration.nix: security.pki.certificateFiles = [ /home/USER/.local/share/mkcert/rootCA.pem ]; # for local development via SSL

Advanced topics

Advanced options

	-cert-file FILE, -key-file FILE, -p12-file FILE
	    Customize the output paths.

	-client
	    Generate a certificate for client authentication.

	-ecdsa
	    Generate a certificate with an ECDSA key.

	-mldsa
	    Generate a certificate with an ML-DSA-65 key (post-quantum,
	    FIPS 204). Requires Go 1.27+.

	-pkcs12
	    Generate a ".p12" PKCS #12 file, also know as a ".pfx" file,
	    containing certificate and key for legacy applications.

	-csr CSR
	    Generate a certificate based on the supplied CSR. Conflicts with
	    all other flags and arguments except -install, -client and -cert-file.

	-name-constraints DOMAIN
	    Constrain the local CA to the given domain (X.509 name constraints).
	    Only effective when the CA is created.

Note: You must place these options before the domain names list.

Example

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

S/MIME

mkcert automatically generates an S/MIME certificate if one of the supplied names is an email address.

mkcert filippo@example.com

Mobile devices

For the certificates to be trusted on mobile devices, you will have to install the root CA. It's the rootCA.pem file in the folder printed by mkcert -CAROOT. However, you have to copy rootCA.pem to rootCA.crt since iOS does not read the .pem extension.

iOS

On iOS, you can either use AirDrop, email the CA to yourself, or serve it from an HTTP server. After opening it, you need to install the profile in Settings > Profile Downloaded and then enable full trust in it.

Android

Save rootCA.pem in any folder other than Downloads. Then go to "System Settings : Security & privacy : Mores security & privacy : Encryption & credentials : Install a certificate : CA certificate". Select "Install anyway" and select rootCA.pem.

You may also need to enable user roots in the development build of your app. See this StackOverflow answer.

Using the root with Node.js

Node does not use the system root store, so it won't accept mkcert certificates automatically. Instead, you will have to set the NODE_EXTRA_CA_CERTS environment variable.

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

Changing the location of the CA files

The CA certificate and its key are stored in an application data folder in the user home. You usually don't have to worry about it, as installation is automated, but the location is printed by mkcert -CAROOT.

If you want to manage separate CAs, you can use the environment variable $CAROOT to set the folder where mkcert will place and look for the local CA files.

Installing the CA on other systems

Installing in the trust store does not require the CA key, so you can export the CA certificate and use mkcert to install it in other machines.

  • Look for the rootCA.pem file in mkcert -CAROOT
  • copy it to a different machine
  • set $CAROOT to its directory
  • run mkcert -install

Remember that mkcert is meant for development purposes, not production, so it should not be used on end users' machines, and that you should not export or share rootCA-key.pem.