Installation

Install NATS Server on your platform using Docker, binary downloads, or package managers

NATS Server is distributed as a single binary with no external dependencies, making installation straightforward on any platform.

System requirements

NATS Server has minimal system requirements and can run on resource-constrained devices including Raspberry Pi.

Minimum requirements:

• CPU: 1 core (2+ cores recommended for production)
• Memory: 128 MB RAM (varies based on workload)
• Disk: 50 MB for binary (additional storage needed for JetStream)
• OS: Linux, macOS, Windows, or any platform with Go support

Default ports:

• 4222: Client connections
• 6222: Cluster routing
• 8222: HTTP monitoring (when enabled)
• 5222: Gateway connections (for super-clusters)

Installation methods

Docker

Docker is the fastest way to get started with NATS Server.

Pull the official image

docker pull nats:latest

The Docker image includes:

• nats-server - The NATS Server binary
• nats - The NATS CLI tool
• nsc - The NATS Security CLI

Run the server

# Basic run
docker run -p 4222:4222 -p 8222:8222 nats:latest

# With JetStream enabled
docker run -p 4222:4222 -p 8222:8222 -v /path/to/storage:/data \
  nats:latest -js --store_dir /data

# With custom configuration
docker run -p 4222:4222 -p 8222:8222 \
  -v /path/to/nats-server.conf:/nats/conf/nats-server.conf \
  nats:latest -c /nats/conf/nats-server.conf

Exposed ports in Docker image

The official Docker image exposes these ports by default:

EXPOSE 4222 8222 6222 5222

The default Docker configuration file is located at /nats/conf/nats-server.conf and includes basic settings for client and cluster ports.

Docker Compose example

version: '3.8'
services:
  nats:
    image: nats:latest
    ports:
      - "4222:4222"
      - "8222:8222"
      - "6222:6222"
    command: ["-js", "--store_dir", "/data", "-m", "8222"]
    volumes:
      - nats-data:/data

volumes:
  nats-data:

Binary Download

Download pre-built binaries for your platform from the GitHub releases page.

Download and install

Linux/macOS

# Download the latest release
curl -L https://github.com/nats-io/nats-server/releases/latest/download/nats-server-v2.x.x-linux-amd64.tar.gz -o nats-server.tar.gz

# Extract
tar -xzf nats-server.tar.gz

# Move to PATH
sudo mv nats-server-v2.x.x-linux-amd64/nats-server /usr/local/bin/

# Verify installation
nats-server --version

Available platforms

Binaries are available for:

• Linux (amd64, arm64, arm6, arm7)
• macOS (amd64, arm64)
• Windows (amd64, arm64)
• FreeBSD (amd64)

Visit GitHub Releases to download the appropriate binary for your platform.

Package Managers

Install NATS Server using your operating system’s package manager.

macOS (Homebrew)

brew install nats-server

Linux (Snap)

sudo snap install nats-server

Windows (Chocolatey)

choco install nats-server

Arch Linux (AUR)

yay -S nats-server

Verify installation

nats-server --version

Build from Source

Build NATS Server from source code if you need the latest development version or want to customize the build.

Prerequisites

• Go 1.20 or later
• Git

Build steps

# Clone the repository
git clone https://github.com/nats-io/nats-server.git
cd nats-server

# Build
go build -o nats-server

# Optionally install
sudo mv nats-server /usr/local/bin/

# Verify
nats-server --version

Build with version information

VERSION=$(git describe --tags --always)
GIT_COMMIT=$(git rev-parse HEAD)

go build -trimpath \
  -ldflags "-w -X server.serverVersion=${VERSION} -X server.gitCommit=${GIT_COMMIT}" \
  -o nats-server .

The build process is the same as used in the official Docker image, which uses Go’s build system with CGO disabled for maximum portability.

Post-installation steps

Verify installation

Check that NATS Server is installed correctly:

# Check version
nats-server --version

# View help
nats-server --help

# Test configuration (if you have a config file)
nats-server -c /path/to/nats-server.conf -t

Start the server

Start NATS Server with default settings:

nats-server

Common startup options:

# Specify host and port
nats-server -a 0.0.0.0 -p 4222

# Enable monitoring
nats-server -m 8222

# Enable JetStream
nats-server -js --store_dir /var/lib/nats

# Use configuration file
nats-server -c /etc/nats/nats-server.conf

# Enable debug logging
nats-server -D

The default configuration binds to 0.0.0.0:4222 which accepts connections from any network interface. For production deployments, bind to specific interfaces and enable authentication.

Configuration

Configuration file location

NATS Server looks for configuration files in these locations:

• Docker: /nats/conf/nats-server.conf
• Linux: /etc/nats/nats-server.conf (conventional)
• macOS: /usr/local/etc/nats-server.conf (conventional)
• Windows: C:\nats\nats-server.conf (conventional)

You can specify a custom location with the -c flag:

nats-server -c /path/to/your/config.conf

Basic configuration example

Create a basic configuration file:

nats-server.conf

# Client port
port: 4222

# HTTP monitoring port
monitor_port: 8222

# Clustering configuration
cluster {
  # Cluster port
  port: 6222

  # Routes for clustering
  routes = [
    nats-route://nats1:6222
    nats-route://nats2:6222
  ]

  # Cluster authorization
  authorization {
    user: ruser
    password: T0pS3cr3t
    timeout: 2
  }
}

# JetStream configuration
jetstream {
  store_dir: "/data/nats/jetstream"
  max_memory_store: 1GB
  max_file_store: 10GB
}

Use nats-server -c your-config.conf -t to test your configuration file for syntax errors before starting the server.

Simple configuration example from source

From the NATS Server repository:

simple.conf

listen: 127.0.0.1:4222

authorization {
  include 'includes/users.conf'
  timeout: 0.5
}

Running as a service

Linux (systemd)

Create a systemd service file at /etc/systemd/system/nats-server.service:

[Unit]
Description=NATS Server
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/nats-server -c /etc/nats/nats-server.conf
ExecReload=/bin/kill -s HUP $MAINPID
Restart=on-failure
User=nats
Group=nats

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl enable nats-server
sudo systemctl start nats-server
sudo systemctl status nats-server

macOS (launchd)

Create a plist file at ~/Library/LaunchAgents/io.nats.server.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>io.nats.server</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/nats-server</string>
    <string>-c</string>
    <string>/usr/local/etc/nats-server.conf</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
</dict>
</plist>

Load the service:

launchctl load ~/Library/LaunchAgents/io.nats.server.plist

Command-line reference

Here’s an overview of common command-line options from the source:

Server options

-a, --addr, --net <host>         Bind to host address (default: 0.0.0.0)
-p, --port <port>                Use port for clients (default: 4222)
-n, --name, --server_name <name> Server name (default: auto)
-P, --pid <file>                 File to store PID
-m, --http_port <port>           HTTP monitoring port
-c, --config <file>              Configuration file
-t                               Test configuration and exit
-sl, --signal <signal>[=<pid>]   Send signal (ldm, stop, quit, term, reopen, reload)

Logging options

-l, --log <file>                 File to redirect log output
-T, --logtime                    Timestamp log entries (default: true)
-D, --debug                      Enable debugging output
-V, --trace                      Trace the raw protocol
-DV                              Debug and trace

JetStream options

-js, --jetstream                 Enable JetStream functionality
-sd, --store_dir <dir>           Set the storage directory

Authorization options

--user <user>                    User required for connections
--pass <password>                Password required for connections
--auth <token>                   Authorization token

TLS options

--tls                            Enable TLS
--tlscert <file>                 Server certificate file
--tlskey <file>                  Private key for certificate
--tlsverify                      Enable TLS, verify clients
--tlscacert <file>               Client certificate CA

Cluster options

--routes <rurl-1, rurl-2>        Routes to solicit and connect
--cluster <cluster-url>          Cluster URL for solicited routes
--cluster_name <string>          Cluster name
--cluster_listen <url>           Cluster URL for incoming routes

Next steps

Quickstart

Follow the quickstart guide to send your first message

Configuration

Learn about advanced configuration options

Security

Secure your NATS Server deployment

Monitoring

Set up monitoring and observability