mkcert Commands Reference

macOS (Homebrew)

brew install mkcert

Linux

# Ubuntu/Debian
sudo apt install libnss3-tools
wget https://github.com/FiloSottile/mkcert/releases/latest/download/mkcert-v*-linux-amd64
chmod +x mkcert-v*-linux-amd64
sudo mv mkcert-v*-linux-amd64 /usr/local/bin/mkcert

# Arch Linux
sudo pacman -S mkcert

Windows (Chocolatey)

choco install mkcert

Windows (Scoop)

scoop bucket add extras scoop install mkcert

Go install (any platform)

go install filippo.io/mkcert@latest

Install local CA

mkcert -install

This creates a local Certificate Authority and installs it in your system's trust store. Run this once per machine.

Create certificate for localhost

mkcert localhost

Creates localhost.pem (certificate) and localhost-key.pem (private key).

Create certificate for localhost with IP

mkcert localhost 127.0.0.1 ::1

Creates certificate valid for localhost, 127.0.0.1 (IPv4), and ::1 (IPv6).

Create certificate for custom domain

mkcert example.test

Creates certificate for custom domain. Remember to add example.test to your /etc/hosts.

Create certificate for multiple domains

mkcert example.com "*.example.com" example.org

Creates multi-domain certificate including wildcard. Quote wildcards to prevent shell expansion.

Create wildcard certificate

mkcert "*.localhost"

Creates certificate valid for any subdomain of localhost (e.g., api.localhost, www.localhost).

Specify output file names

mkcert -cert-file myapp.crt -key-file myapp.key localhost

Useful for specific naming requirements or integration with tools.

Create certificate with custom output names

mkcert -cert-file cert.pem -key-file key.pem localhost

Note: mkcert creates certificates valid for 825 days (maximum for Chrome). This cannot be customized.

Create certificate for specific IP addresses

mkcert 192.168.1.100 10.0.0.50

Create client certificate

mkcert -client localhost

Creates certificate for client authentication (mTLS).

Generate PKCS#12 bundle

mkcert -pkcs12 localhost

Creates localhost.p12 bundle containing both certificate and key. Useful for Java applications.

Use custom CA location

export CAROOT="/path/to/custom/ca"
mkcert localhost

Useful for team sharing or CI/CD environments.

View CA certificate location

mkcert -CAROOT

Shows where the CA files are stored (typically ~/Library/Application Support/mkcert on macOS, ~/.local/share/mkcert on Linux).

Uninstall local CA

mkcert -uninstall

Removes the CA from system trust stores but keeps CA files for existing certificates.

Share CA with team (manual)

# On first machine
mkcert -CAROOT
# Copy rootCA.pem and rootCA-key.pem to shared location

# On other machines
export CAROOT="/path/to/shared/ca"
mkcert -install

⚠️ Warning: Keep rootCA-key.pem secure. Anyone with this key can create trusted certificates.

View CA certificate

CAROOT=$(mkcert -CAROOT)
openssl x509 -text -noout -in "$CAROOT/rootCA.pem"

nginx configuration

# Generate certificate
mkcert -cert-file /etc/nginx/certs/cert.pem \
       -key-file /etc/nginx/certs/key.pem \
       localhost 127.0.0.1

# In nginx.conf
server {
    listen 443 ssl;
    server_name localhost;

    ssl_certificate /etc/nginx/certs/cert.pem;
    ssl_certificate_key /etc/nginx/certs/key.pem;
}

Apache configuration

# Generate certificate
mkcert -cert-file /etc/apache2/certs/cert.pem \
       -key-file /etc/apache2/certs/key.pem \
       localhost

# In apache2.conf or site config
<VirtualHost *:443>
    ServerName localhost
    SSLEngine on
    SSLCertificateFile /etc/apache2/certs/cert.pem
    SSLCertificateKeyFile /etc/apache2/certs/key.pem
</VirtualHost>

Caddy configuration

# Generate certificate
mkcert localhost

# Caddyfile
localhost {
    tls cert.pem key.pem
    reverse_proxy localhost:3000
}

Node.js (Express) example

const https = require('https');
const fs = require('fs');
const express = require('express');

const app = express();

const options = {
  key: fs.readFileSync('localhost-key.pem'),
  cert: fs.readFileSync('localhost.pem')
};

https.createServer(options, app).listen(3000);

Python (Flask) example

from flask import Flask

app = Flask(__name__)

if __name__ == '__main__':
    app.run(
        ssl_context=('localhost.pem', 'localhost-key.pem'),
        port=5000
    )

React development server

# Generate certificate
mkcert -cert-file cert.pem -key-file key.pem localhost

# Create .env file
HTTPS=true
SSL_CRT_FILE=cert.pem
SSL_KEY_FILE=key.pem

# Start dev server
npm start

Vite development server

// vite.config.js
import { defineConfig } from 'vite'
import fs from 'fs'

export default defineConfig({
  server: {
    https: {
      key: fs.readFileSync('localhost-key.pem'),
      cert: fs.readFileSync('localhost.pem'),
    }
  }
})

Next.js development server

# Generate certificate
mkcert -cert-file cert.pem -key-file key.pem localhost

# Create server.js
const { createServer } = require('https')
const { parse } = require('url')
const next = require('next')
const fs = require('fs')

const dev = process.env.NODE_ENV !== 'production'
const app = next({ dev })
const handle = app.getRequestHandler()

const httpsOptions = {
  key: fs.readFileSync('./key.pem'),
  cert: fs.readFileSync('./cert.pem')
}

app.prepare().then(() => {
  createServer(httpsOptions, (req, res) => {
    const parsedUrl = parse(req.url, true)
    handle(req, res, parsedUrl)
  }).listen(3000, (err) => {
    if (err) throw err
    console.log('> Ready on https://localhost:3000')
  })
})

Docker development

# Generate certificate
mkcert -cert-file certs/cert.pem -key-file certs/key.pem localhost

# docker-compose.yml
services:
  web:
    build: .
    volumes:
      - ./certs:/app/certs:ro
    environment:
      - SSL_CERT=/app/certs/cert.pem
      - SSL_KEY=/app/certs/key.pem
    ports:
      - "443:443"

Supported platforms

mkcert automatically configures trust for:

• macOS system trust store and Keychain
• Windows system root store
• Linux NSS databases (Firefox, Chrome, Chromium)
• Java keytool (if JAVA_HOME is set)

Firefox on Linux (manual)

# Install NSS tools
sudo apt install libnss3-tools  # Debian/Ubuntu
sudo yum install nss-tools      # RHEL/CentOS

# Then run mkcert -install

Mobile devices

For iOS/Android testing:

• Get CA location: mkcert -CAROOT
• Copy rootCA.pem to device
• Install as trusted certificate in device settings
• iOS: Settings → General → VPN & Device Management → Install Profile
• Android: Settings → Security → Install from storage

Certificate not trusted in browser

Try reinstalling the CA:

mkcert -uninstall
mkcert -install

Firefox on Linux not trusting certificates

Ensure NSS tools are installed:

sudo apt install libnss3-tools

"wildcard in leftmost label" error

Some browsers don't allow wildcards in the leftmost position. Use specific subdomains:

mkcert "*.example.test" example.test

Check certificate validity

openssl x509 -text -noout -in localhost.pem | grep -A2 "Validity"

Test HTTPS connection

curl -v https://localhost:3000

Security

• ⚠️ mkcert is for development only - never use in production
• Keep rootCA-key.pem secure - treat it like a password
• Don't commit certificates or CA files to version control
• Add *.pem and *.p12 to .gitignore
• Uninstall CA when no longer needed: mkcert -uninstall

Team workflows

• Each developer should run mkcert -install independently
• Share only generated certificates (not CA files) if needed
• Document mkcert setup in project README
• Consider using the same domain names across team

Domain naming

• Use .test or .local for development domains
• Add custom domains to /etc/hosts: 127.0.0.1 myapp.test
• Use wildcards for subdomains: *.myapp.test
• Include both domain and localhost in certificates