Installation - NATS Server

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
Binary Download
Package Managers
Build from Source

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:

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

Download and install

# 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.

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 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

Get Started

Deployment

Architecture

Features

Operations

Configuration

​System requirements

​Installation methods

​Pull the official image

​Run the server

​Exposed ports in Docker image

​Docker Compose example

​Download and install

​Available platforms

​macOS (Homebrew)

​Linux (Snap)

​Windows (Chocolatey)

​Arch Linux (AUR)

​Verify installation

​Prerequisites

​Build steps

​Build with version information

​Post-installation steps

​Verify installation

​Start the server

​Configuration

​Configuration file location

​Basic configuration example

​Simple configuration example from source

​Running as a service

​Linux (systemd)

​macOS (launchd)

​Command-line reference

​Server options

​Logging options

​JetStream options

​Authorization options

​TLS options

​Cluster options

​Next steps

Quickstart

Configuration

Security

Monitoring

Build docs developers (and LLMs) love

System requirements

Installation methods

Pull the official image

Run the server

Exposed ports in Docker image

Docker Compose example

Download and install

Available platforms

macOS (Homebrew)

Linux (Snap)

Windows (Chocolatey)

Arch Linux (AUR)

Verify installation

Prerequisites

Build steps

Build with version information

Post-installation steps

Verify installation

Start the server

Configuration

Configuration file location

Basic configuration example

Simple configuration example from source

Running as a service

Linux (systemd)

macOS (launchd)

Command-line reference

Server options

Logging options

JetStream options

Authorization options

TLS options

Cluster options

Next steps