# Getting Started with NATS

Get up and running with NATS in minutes. This guide will walk you through installation, basic setup, and your first NATS application.

## Installation

### Quick Start with Docker

The fastest way to get NATS running:

```
docker run -p 4222:4222 -p 8222:8222 nats:latest
```

This starts NATS Server with:

* Client connections on port 4222
* HTTP monitoring on port 8222

### Install NATS Server

#### macOS

```
brew install nats-server
```

#### Linux

```
curl -L https://github.com/nats-io/nats-server/releases/latest/download/nats-server-linux-amd64.zip -o nats-server.zip
unzip nats-server.zip
sudo cp nats-server /usr/local/bin
```

#### Windows

Download the latest release from [GitHub Releases](https://github.com/nats-io/nats-server/releases).

### Verify Installation

```
nats-server --version
```

## Start NATS Server

### Basic Server

```
nats-server
```

### With Monitoring

```
nats-server -m 8222
```

Visit <http://localhost:8222> to see server metrics.

### With JetStream (Persistence)

```
nats-server -js
```

## Install NATS CLI

The NATS CLI tool helps you interact with NATS:

```
# macOS
brew install nats-io/nats-tools/nats

# Linux
curl -L https://github.com/nats-io/natscli/releases/latest/download/nats-linux-amd64.zip -o nats-cli.zip
unzip nats-cli.zip
sudo cp nats /usr/local/bin
```

## Your First NATS Application

### Using the CLI

```
# Subscribe to a subject
nats sub hello &

# Publish a message
nats pub hello "Hello NATS!"
```

### Install Client Libraries

#### CLI

```
# The NATS CLI is already installed (see above)
# You can use it directly for pub/sub operations
```

#### JavaScript/TypeScript

```
npm install nats
```

#### Go

```
go get github.com/nats-io/nats.go
```

#### Java

Gradle

```
dependencies {
  implementation 'io.nats:jnats:2.25.2'
}
```

Maven

```
<dependency>
    <groupId>io.nats</groupId>
    <artifactId>jnats</artifactId>
    <version>2.25.2</version>
</dependency>
```

#### Rust

Cargo.toml

```
[dependencies]
async-nats = "0.47.0"
tokio = { version = "1", features = ["full"] }
```

#### C#/.NET

```
dotnet add package NATS.Net
```

See [NATS.Net on NuGet](https://www.nuget.org/packages/NATS.Net) for the latest version.

### Publisher Example

#### CLI

```
#!/bin/bash

# Publish a message to demo.nats.io
nats pub --server=demo.nats.io hello "Hello NATS!"
```

#### JavaScript/TypeScript

```
/*
 * Copyright 2026 The NATS Authors
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

// import the connect function from a transport
import { connect } from "@nats-io/transport-deno";

// connect to NATS demo server
const nc = await connect();

// publish a message to the 'hello' subject
nc.publish("hello", "Hello NATS!");
console.log("Message published to hello");

// drain the connection (flushes and closes)
await nc.drain();
```

#### Go

```
package main

import (
	"log"

	"github.com/nats-io/nats.go"
)

func main() {
	// Connect to NATS demo server
	nc, err := nats.Connect("demo.nats.io")
	if err != nil {
		log.Fatal(err)
	}
	defer nc.Close()

	// Publish a message
	err = nc.Publish("hello", []byte("Hello NATS!"))
	if err != nil {
		log.Fatal(err)
	}

	log.Println("Message published to hello")
}
```

#### Python

```
async def main():
    # Connect to NATS demo server
    nc = await client.connect("nats://demo.nats.io")

    # Publish a message to the subject "hello"
    await nc.publish("hello", b"Hello NATS!")
    await nc.flush()

    print("Message published to hello")

    await nc.close()
```

#### Java

```
public static void main(String[] args) {
    try (Connection nc = Nats.connect("demo.nats.io")) {
        // Publish a message to the subject "hello"
        byte[] data = "Hello NATS!".getBytes(StandardCharsets.UTF_8);
        nc.publish("hello", data);
        System.out.println("Message published to hello");
    }
    catch (InterruptedException e) {
        // can be thrown by connect
        Thread.currentThread().interrupt();
    }
    catch (IOException e) {
        // can be thrown by connect
    }
}
```

#### Rust

```
// Connect to NATS demo server
let client = async_nats::connect("demo.nats.io").await?;

// Publish a message to the subject "hello"
client.publish("hello", "Hello NATS!".into()).await?;
client.flush().await?;

println!("Message published to hello");
```

#### C#/.NET

```
await using var client = new NatsClient("demo.nats.io");

// Publish a message to the subject "hello"
await client.PublishAsync("hello", "Hello NATS!");
```

### Subscriber Example

#### CLI

```
#!/bin/bash

# Subscribe to messages from demo.nats.io
nats sub --server=demo.nats.io hello
```

#### JavaScript/TypeScript

```
// Subscribe to the "weather.updates" subject; auto-close after 1 message
const sub = nc.subscribe("weather.updates");

// iterate over messages received (sub will end after the first message)
for await (const msg of sub) {
  console.log(`Received: ${msg.string()}`);
  break;
}
```

#### Go

```
package main

import (
	"log"
	"runtime"

	"github.com/nats-io/nats.go"
)

func main() {
	// Connect to NATS demo server
	nc, err := nats.Connect("demo.nats.io")
	if err != nil {
		log.Fatal(err)
	}
	defer nc.Close()

	// Subscribe to 'hello'
	_, err = nc.Subscribe("hello", func(msg *nats.Msg) {
		log.Printf("Received: %s", string(msg.Data))
	})
	if err != nil {
		log.Fatal(err)
	}

	log.Println("Listening for messages on 'hello'...")

	// Keep the connection alive
	runtime.Goexit()
}
```

#### Python

```
async def main():
    nc = await client.connect("nats://demo.nats.io")

    # Asynchronous subscriber - iterate messages in a background task
    async_sub = await nc.subscribe("hello")

    async def async_handler():
        async for msg in async_sub:
            print(f"Asynchronous Subscriber Received: {msg.data.decode()}")

    asyncio.create_task(async_handler())

    # Synchronous subscription
    sync_sub = await nc.subscribe("hello")

    print("Waiting for message on 'hello'")

    # Process messages synchronously
    while True:
        try:
            msg = await sync_sub.next(timeout=1)
            print(f"Synchronous Subscriber Received: {msg.data.decode()}")
        except TimeoutError:
            break

    await nc.close()
```

#### Java

```
public static void main(String[] args) {
    try (Connection nc = Nats.connect("demo.nats.io")) {
        // Asynchronous Subscriber requires a dispatcher
        // Dispatchers can be shared
        Dispatcher d = nc.createDispatcher(msg -> {
            System.out.println("Asynchronous Subscriber Received: " +
                new String(msg.getData(), StandardCharsets.UTF_8));
        });

        // Subscribe to 'hello' subject
        d.subscribe("hello");

        // Subscribe to 'hello' synchronously
        Subscription syncSub = nc.subscribe("hello");

        System.out.println("Waiting for message on 'hello'");

        // Process messages
        Message m = syncSub.nextMessage(1000);
        while (m != null) {
            System.out.println("Synchronous Subscriber Received: " +
                new String(m.getData(), StandardCharsets.UTF_8));
            m = syncSub.nextMessage(1000);
        }
    }
    catch (InterruptedException e) {
        // can be thrown by connect
        Thread.currentThread().interrupt();
    }
    catch (IOException e) {
        // can be thrown by connect
    }
}
```

#### Rust

```
// Connect to NATS demo server
let client = async_nats::connect("demo.nats.io").await?;

// Subscribe to the 'hello' subject
let mut subscriber = client.subscribe("hello").await?;
println!("Listening for messages on 'hello'...");

// Process messages
while let Some(msg) = subscriber.next().await {
    println!("Received: {}", String::from_utf8_lossy(&msg.payload));
}
```

#### C#/.NET

```
await using var client = new NatsClient("demo.nats.io");

// Subscribe to 'hello' and process messages
await foreach (var msg in client.SubscribeAsync<string>("hello"))
{
    output.WriteLine($"Received: {msg.Data}");
}
```

### Running the Examples

#### CLI

```
# Terminal 1 - Start subscriber
nats sub hello

# Terminal 2 - Publish messages
nats pub hello "Hello NATS!"
nats pub hello "Welcome to messaging"

# Request-Reply pattern
# Terminal 1 - Start replier
nats reply hello "Hi there!"

# Terminal 2 - Send request
nats request hello "Anyone there?" --timeout=2s
```

#### JavaScript/TypeScript

```
# Terminal 1 - Start subscriber
node subscribe.js

# Terminal 2 - Run publisher
node publish.js
```

#### Go

```
# Terminal 1 - Start subscriber
go run subscribe.go

# Terminal 2 - Run publisher
go run publish.go
```

#### Java

```
It's best to run the examples from your IDE or 
command line where Java is installed.

Clone https://github.com/nats-io/nats.java
and navigate to src/main/java/io/nats/examples/natsIoDoc
```

#### Rust

```
# Terminal 1 - Start subscriber
cargo run --bin subscribe

# Terminal 2 - Run publisher
cargo run --bin publish
```

#### C#/.NET

```
It's best to run the examples from your IDE or
command line where the .NET SDK is installed.

Clone https://github.com/nats-io/nats.net
and navigate to examples/Example.NatsIODocs
```

## Next Steps

Congratulations! You've successfully:

* ✅ Installed NATS Server
* ✅ Published and subscribed to messages
* ✅ Built your first NATS application

### What to explore next:

1. **[Request-Reply Pattern](/concepts/request-reply.md)** - Synchronous communication
2. **[Queue Groups](/concepts/queue-groups.md)** - Load balancing
3. **[Subjects](/concepts/subjects.md)** - Understanding subject-based messaging
4. **[Pub/Sub Basics](/concepts/pub-sub-basics.md)** - Core messaging patterns

### Client Libraries

NATS has official clients for:

* [Go](https://github.com/nats-io/nats.go)
* [Java](https://github.com/nats-io/nats.java)
* [JavaScript/TypeScript](https://github.com/nats-io/nats.js)
* [Python](https://github.com/nats-io/nats.py)
* [Rust](https://github.com/nats-io/nats.rs)
* [C](https://github.com/nats-io/nats.c)
* [.NET](https://github.com/nats-io/nats.net)

### Resources

* [NATS by Example](https://natsbyexample.com) - Interactive examples
* [GitHub Examples](https://github.com/nats-io/nats-examples) - Sample applications
* [Slack Community](https://natsio.slack.com) - Get help from the community