Github url

mkcert

by FiloSottile

FiloSottile /mkcert

A simple zero-config tool to make locally trusted development certificates with any names you'd like...

24.7K Stars 1.0K Forks Last release: 8 months ago (v1.4.1) BSD 3-Clause "New" or "Revised" License 137 Commits 11 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

mkcert

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

$ mkcert -install Created a new local CA at "/Users/filippo/Library/Application Support/mkcert" πŸ’₯ The local CA is now installed in the system trust store! ⚑️ The local CA is now installed in the Firefox trust store (requires browser restart)! 🦊 $ mkcert example.com "\*.example.com" example.test localhost 127.0.0.1 ::1 Using the local CA at "/Users/filippo/Library/Application Support/mkcert" ✨ 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 brew install nss # if you use Firefox

or MacPorts.

sudo port selfupdate sudo port install mkcert sudo port 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 -or- sudo zypper install mozilla-nss-tools

Then you can install using Linuxbrew

brew install mkcert

or 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 the pre-built binaries.

For Arch Linux users, [

mkcert

](https://www.archlinux.org/packages/community/x86_64/mkcert/) is available on the official Arch Linux repository.

sudo pacman -Syu mkcert

Windows

On Windows, use Chocolatey

choco install mkcert

or use Scoop

scoop bucket add extras scoop install mkcert

or build from source (requires Go 1.10+), 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).

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. -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 and -cert-file.

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 [email protected]

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

.

On iOS, you can either use AirDrop, email the CA to yourself, or serve it from an HTTP server. After installing it, you must enable full trust in it. Note: earlier versions of mkcert ran into an iOS bug, if you can't see the root in "Certificate Trust Settings" you might have to update mkcert and regenerate the root.

For Android, you will have to install the CA and then 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

](https://nodejs.org/api/cli.html#cli_node_extra_ca_certs_file) 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

.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.