# 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 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 ``` io.nats jnats 2.25.2 ``` #### 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("nats://localhost:4222")) { // 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("nats://localhost:4222")) { // 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("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