ntfy is a super simple pub-sub notification service. It allows you to send desktop notifications via scripts.

Related tags

Messaging ntfy


ntfy (pronounce: notify) is a super simple pub-sub notification service. It allows you to send desktop and (soon) phone notifications via scripts. I run a free version of it on ntfy.sh. No signups or cost.


Subscribe to a topic

Topics are created on the fly by subscribing to them. You can create and subscribe to a topic either in a web UI, or in your own app by subscribing to an SSE/EventSource, or a JSON or raw feed.

Because there is no sign-up, the topic is essentially a password, so pick something that's not easily guessable.

Here's how you can create a topic mytopic, subscribe to it topic and wait for events. This is using curl, but you can use any library that can do HTTP GETs:

# Subscribe to "mytopic" and output one message per line (\n are replaced with a space)
curl -s ntfy.sh/mytopic/raw

# Subscribe to "mytopic" and output one JSON message per line
curl -s ntfy.sh/mytopic/json

# Subscribe to "mytopic" and output an SSE stream (supported via JS/EventSource)
curl -s ntfy.sh/mytopic/sse

You can easily script it to execute any command when a message arrives. This sends desktop notifications (just like the web UI, but without it):

while read msg; do 
  notify-send "$msg"
done < <(stdbuf -i0 -o0 curl -s ntfy.sh/mytopic/raw)

Publish messages

Publishing messages can be done via PUT or POST using. Here's an example using curl:

curl -d "long process is done" ntfy.sh/mytopic

Messages published to a non-existing topic or a topic without subscribers will not be delivered later. There is (currently) no buffering of any kind. If you're not listening, the message won't be delivered.


Please check out the releases page for binaries and deb/rpm packages.

  1. Install ntfy using one of the methods described below
  2. Then (optionally) edit /etc/ntfy/config.yml
  3. Then just run it with ntfy (or systemctl start ntfy when using the deb/rpm).

Binaries and packages

Debian/Ubuntu (from a repository):

curl -sSL https://archive.heckel.io/apt/pubkey.txt | sudo apt-key add -
sudo apt install apt-transport-https
sudo sh -c "echo 'deb [arch=amd64] https://archive.heckel.io/apt debian main' > /etc/apt/sources.list.d/archive.heckel.io.list"  
sudo apt update
sudo apt install ntfy

Debian/Ubuntu (manual install):

sudo apt install tmux
wget https://github.com/binwiederhier/ntfy/releases/download/v0.0.4/ntfy_0.0.4_amd64.deb
dpkg -i ntfy_0.0.4_amd64.deb


rpm -ivh https://github.com/binwiederhier/ntfy/releases/download/v0.0.4/ntfy_0.0.4_amd64.rpm


docker run --rm -it binwiederhier/ntfy


go get -u heckel.io/ntfy

Manual install (any x86_64-based Linux):

wget https://github.com/binwiederhier/ntfy/releases/download/v0.0.4/ntfy_0.0.4_linux_x86_64.tar.gz
sudo tar -C /usr/bin -zxf ntfy_0.0.4_linux_x86_64.tar.gz ntfy


Building ntfy is simple. Here's how you do it:

make build-simple
# Builds to dist/ntfy_linux_amd64/ntfy

To build releases, I use GoReleaser. If you have that installed, you can run make build or make build-snapshot.


Isn't this like ...?

Probably. I didn't do a whole lot of research before making this.

Can I use this in my app?

Yes. As long as you don't abuse it, it'll be available and free of charge.

What are the uptime guarantees?

Best effort.

Why is the web UI so ugly?

I don't particularly like JS or dealing with CSS. I'll make it pretty after it's functional.

Will you know what topics exist, can you spy on me?

If you don't trust me or your messages are sensitive, run your ntfy on your own server. That said, the logs do not contain any topic names or other details about you.


  • add HTTPS


I welcome any and all contributions. Just create a PR or an issue.


Made with โค๏ธ by Philipp C. Heckel, distributed under the Apache License 2.0.

Third party libraries and resources:

  • iOS app

    iOS app

    ~If you're interested in making an iOS app, I'm more than happy to help out. Unfortunately I don't have an iPhone or a Mac so it's a little tricky for me.~

    ~Significant work has been done here (https://github.com/Copephobia/ntfy-ios), but it's stale now, sadly.~

    I have picked up the work in https://github.com/binwiederhier/ntfy-ios and will hopefully be able to release soon.

    enhancement in-progress ๐Ÿƒ ios 
    opened by binwiederhier 74
  • Auth


    I would like to require authentication to pub/sub to topics at least on private servers. I think Google Identity would be a good provider here since authenticating to it is a familiar part of the types of workflows I would like to incorporate this into.

    enhancement android-app in-progress ๐Ÿƒ ๐Ÿ”ฅ HOT unified-push 
    opened by dwmccheyne 52
  • ๐Ÿ‘ถ Baby break - Baby girl was born 8/30 :partying_face:

    ๐Ÿ‘ถ Baby break - Baby girl was born 8/30 :partying_face:

    Hey folks, my daughter ~~is about to be born~~ was born 8/30/22, so I'll be taking some time off from working on ntfy. I'll likely return to working on features and bugs in a few weeks. I hope you understand.


    opened by binwiederhier 40
  • Maximize battery life

    Maximize battery life

    Having something like the following would be very cool, though it might be difficult to build. Basically:

    1. Detect that the device is on a new network (based on SSID, mobile data status, etc)
    2. The device calls the subscribe URL (/json or /sse) with ?keepalive=test
    3. The server sends keepalives at a known increasing interval, 30s, 35s, 40s, 45s ...
    4. At some point (say 90 sec), the client no longer receives the keepalive on time - it detects that the connection was disrupted.
    5. Next, it can connect to the server with ?keepalive=85 and receive keepalives every 85s.
    6. This information can be cached per SSID/mobile data/etc for some time.
    enhancement android-app 
    opened by karmanyaahm 22
  • default-user and default-password in client.yml not working

    default-user and default-password in client.yml not working

    I've created a file in ~/.config/ntfy/client.yml with this content

    default-host: https://push.pablo.tools
    default-user: pinpox
    default-password: mysupersecretspassword

    But the client seems to ingnore the values:

    $ ntfy pub --config ~/.config/ntfy/client.yml https://push.pablo.tools/test                                                                                                                                                         

    Using the NTFY_USER environment variable works, so I know the crendentials are in fact correct:

    $ export NTFY_USER=pinpox:mysupersecretspassword
    $ ntfy pub test test                                                                                                                                                                                                                
    ๐Ÿชฒ bug server 
    opened by pinpox 20
  • Docker not starting with v1.18.1 on arm64

    Docker not starting with v1.18.1 on arm64

    I am trying to run ntfy on docker on a Raspberry 4. Executing

    docker run -p -it binwiederhier/ntfy serve

    stops after a few seconds without any output, and return code 132. (same if explicitly using the arm64-tagged image)

    Running on Ubuntu 20.04.4 LTS (GNU/Linux 5.4.0-1056-raspi aarch64)

    ๐Ÿชฒ bug build server 
    opened by iexos 19
  • Support for webhooks from Prometheus, GitHub, ...

    Support for webhooks from Prometheus, GitHub, ...

    It would be nice if ntfy.sh could receive the json format from alertmanager: https://www.prometheus.io/docs/alerting/latest/configuration/#webhook_config

    And the Annotiation shoud be the Title, generatedURL as message and labels as Tags exclude label "priority" should be used for Priority

    PS: With one request multiple messages would be created ...

    enhancement integrations server 
    opened by genofire 19
  • Consider Including a Matrix Gateway endpoint as part of ntfy

    Consider Including a Matrix Gateway endpoint as part of ntfy

    Hello, this is kind of awkward to ask as the use-case is quite specific, but at the same time it should be fairly self-contained.


    The core issue is using UnifiedPush in conjunction with a Matrix Client and Server. The Matrix Client will pass a push URL to the Matrix server. However, the Matrix spec mandates some endpoints for push servers: https://spec.matrix.org/v1.2/push-gateway-api/

    Basically, the spec mandates the use of the /_matrix/push/v1/notify path.

    Therefore, one has to use an intermediate gateway before forwarding requests to ntfy. When users do not use their own, clients use default ones, which led to rate-limiting: #144

    Benefit to users

    Currently, users can host a gateway themselves through the common-proxies project, or some other rewrite proxy.

    That's one more step for users, who might feel discouraged from doing so. Including that gateway would increase privacy, for users of the public ntfy instance, but even more so for users who host their own homeserver and ntfy instance, as push messages do not need to travel through third-party gateways.

    Needed changes

    The set of features to support is relatively simple:

    • Answer
       GET /_matrix/push/v1/notify


      HTTP/1.1 200 OK
    • Handle Pushes on that endpoint. From the spec:
      POST /_matrix/push/v1/notify
      "notification": {
        "content": {
          "body": "I'm floating in a most peculiar way.",
          "msgtype": "m.text"
        "counts": {
          "missed_calls": 1,
          "unread": 2
        "devices": [
            "app_id": "org.matrix.matrixConsole.ios",
            "data": {},
            "pushkey": "https://ntfy.sh/exampleTopicID?up=1",
            "pushkey_ts": 12345678,
            "tweaks": {
              "sound": "bing"
        "event_id": "$3957tyerfgewrf384",
        "prio": "high",
        "room_alias": "#exampleroom:matrix.org",
        "room_id": "!slw48wfj34rtnrf:example.com",
        "room_name": "Mission Control",
        "sender": "@exampleuser:matrix.org",
        "sender_display_name": "Major Tom",
        "type": "m.room.message"

      That should be forwarded to the topic in json_body["notification"]["devices"][0]["pushkey"]. In this case, exampleTopicID?up=1.

    • Answer that push with:
      HTTP/1.1 200 OK

      Technically one could reject events for some topics that have never been listened to, or were deleted from the app, but that sounds a bit alien to the way ntfy works.

    That's all. This should only be necessary until the Matrix Spec Change 2970 lands to delete that requirement and allow arbitrary paths, so that's your call.

    Impact assessment

    One more thing to expect: on the public ntfy instance, FluffyChat's and schildichat's public gateways wouldn't be used anymore, so individual Matrix servers would be subjected to rate-limiting instead, probably Matrix.org, kde.org and mozilla.org, as they are the biggest I can think of right now.

    On the other hand, it makes it easier to single out abusive Matrix homeservers without locking users out. Moreover, as more clients appear (Element will soon support UP), more gateways will appear.

    It might also make it easier to rate-limit matrix separately while the MSC isn't merged.

    enhancement server unified-push 
    opened by MayeulC 17
  • arm64 build randomly crashes with varying stack traces

    arm64 build randomly crashes with varying stack traces

    $ qemu-aarch64 dist/ntfy_arm64_linux_arm64/ntfy
    fatal error: qemu: uncaught target signal 11 (Segmentation fault) - core dumped
    standard_init_linux.go:228: exec user process caused: exec format error
    ๐Ÿชฒ bug server 
    opened by binwiederhier 16
  • Opening ntfy.sh link in a browser on Android opens the app and subscribes to the topic if the app is installed

    Opening ntfy.sh link in a browser on Android opens the app and subscribes to the topic if the app is installed

    A scenario may be:

    • I have the ntfy.sh app installed on my Android device
    • A browser page or application (like Slack) has a URL to a ntfy.sh topic

    If I click on the ntfy.sh link, it will attempt to open the app and subscribe to the topic, so that I can view it from there.

    If I do not have the ntfy.sh link, it will display the web page for that topic.

    enhancement android-app in-progress ๐Ÿƒ 
    opened by Copephobia 13
  • CLI on Termux (Android) fails to connect

    CLI on Termux (Android) fails to connect

    I compiled the cli under Termux (the precompiled binaries didn't work). Compilation worked, but pub/sub doesn't work.

    Here's compilation output:

    $ make cli-client
    mkdir -p server/docs server/site
    touch server/docs/index.html server/site/app.html
    # This is a target to build the CLI (excluding the server) manually. This should work on Linux/macOS/Windows.
    # Use this for development, if you really don't want to install GoReleaser ...
    mkdir -p dist/ntfy_client server/docs
    CGO_ENABLED=0 go build \
            -o dist/ntfy_client/ntfy \
            -tags noserver \
            -ldflags \
            "-X main.version=v1.27.2 -X main.commit=69d6cdd -X main.date=1656031518"
    go: downloading github.com/urfave/cli/v2 v2.10.2
    go: downloading gopkg.in/yaml.v2 v2.4.0
    go: downloading github.com/gabriel-vasile/mimetype v1.4.0
    go: downloading github.com/olebedev/when v0.0.0-20211212231525-59bd4edcf9d6
    go: downloading golang.org/x/term v0.0.0-20220526004731-065cf7ba2467
    go: downloading golang.org/x/time v0.0.0-20220609170525-579cf78fd858
    go: downloading golang.org/x/sys v0.0.0-20220622161953-175b2fd9d664
    go: downloading github.com/AlekSi/pointer v1.2.0
    go: downloading github.com/pkg/errors v0.9.1
    go: downloading gopkg.in/yaml.v3 v3.0.1
    go: downloading github.com/BurntSushi/toml v1.1.0
    go: downloading github.com/cpuguy83/go-md2man/v2 v2.0.2
    go: downloading github.com/russross/blackfriday/v2 v2.1.0
    go: downloading golang.org/x/net v0.0.0-20220622184535-263ec571b305

    Here's output of a pub command:

    $ ./dist/ntfy_client/ntfy pub dan000-tests
    Post "https://ntfy.sh/dan000-tests": dial tcp: lookup ntfy.sh on [::1]:53: read udp [::1]:59557->[::1]:53: read: connection refused

    Similar output for sub command. Adding -d and --trace didn't add any extra output.

    curl works fine, however.

    android-app question 
    opened by goodevilgenius 12
  • The nginx configuration(and the one used by ntfy.sh) leaks topic name/auth query in logs

    The nginx configuration(and the one used by ntfy.sh) leaks topic name/auth query in logs

    In https://github.com/binwiederhier/ntfy-ansible/blob/eaa9b7c7ee96adc106317ddfaf07dc28e7d6bde1/roles/nginx/files/nginx.conf#L48 log_format includes $request which contains the request path, which in turn leaks topic names. This is mitigated with the use of http basic auth, but in the case of authentication via a query parameter the credentials are also logged.

    It's is not a huge issue, but potentially could end up quite bad if someone is able to see the log(via LFI? An admin accidentally forgetting they were screensharing? Idk), so maybe it's worth fixing?

    The docs for setting up a reverse proxy in front of ntfy(https://docs.ntfy.sh/config/?h=nginx#nginxapache2caddy) don't explicitly set the log format themselves, but the default configuration used by most linux distributions will include the $request param

    opened by MaeIsBad 0
  • ClamAV detected Coinminer in docker image

    ClamAV detected Coinminer in docker image

    Was scanning the other day and got the warning on my containerd folder. Sure enough I can reproduce it by saving the docker image.

    shawn@SHAWN-DESKTOP:~$ docker pull docker.io/binwiederhier/ntfy
    Using default tag: latest
    latest: Pulling from binwiederhier/ntfy
    Digest: sha256:d13fda9b2741de857c3c9be2f89b24c514922da7aa3da060580640865beffdc1
    Status: Image is up to date for binwiederhier/ntfy:latest
    shawn@SHAWN-DESKTOP:~$ docker save -o ntfy.tar docker.io/binwiederhier/ntfy@sha256:d13fda9b2741de857c3c9be2f89b24c514922da7aa3da060580640865beffdc1
    shawn@SHAWN-DESKTOP:~$ mkdir ntfy
    shawn@SHAWN-DESKTOP:~$ tar -xf ntfy.tar -C ntfy
    shawn@SHAWN-DESKTOP:~$ clamscan -r -i ntfy
    /home/shawn/ntfy/785c9d282366f58ab6d7a65b79e22192780e823a0455bddbbf84facdc4732370/layer.tar: Unix.Packed.Coinminer-6856324-0 FOUND
    ----------- SCAN SUMMARY -----------
    Known viruses: 8647316
    Engine version: 0.103.6
    Scanned directories: 3
    Scanned files: 8
    Infected files: 1
    Data scanned: 34.96 MB
    Data read: 26.05 MB (ratio 1.34:1)
    Time: 16.469 sec (0 m 16 s)
    Start Date: 2023:01:09 03:50:34
    End Date:   2023:01:09 03:50:50
    opened by shawnhwei 4
  • Paste images from clipboard

    Paste images from clipboard

    Currently NTFY supports attaching a file from a local source or via an external URL. It would be cool if one could paste from clipboard and the file uploading just worked. An use case I can think of is quickly sharing an image from one computer to another.

    opened by rounakdatta 3
  • Modularize init and install scripts and remove hard requirement on systemd

    Modularize init and install scripts and remove hard requirement on systemd

    Currently init and install scripts makes the assumption you are installing ntfy on a distro with systemd present.

    As the unix-like world isn't just about systemd, and it is often the case systemd is prohibited, the scripts used needs to facilitate and support the most commonly used non-systemd init systems like SysV, OpenRC, s6, runit and so on, for users who runs Alpine Linux, Devuan Linux or any other non-systemd distro as their server base. There are several ways this could be solved, but the most straight forward way, I would suggest to have have an init script generator which can be invoked in the postinst step and output an init script based on the target system.

    opened by code-kungfu 0
  • emersion/go-smtp upgrade to v0.16.0 introduced breaking changes

    emersion/go-smtp upgrade to v0.16.0 introduced breaking changes

    See https://github.com/emersion/go-smtp/issues/208

    v0.16.0 changes the API of the library (see https://github.com/emersion/go-smtp/compare/v0.15.0...v0.16.0). I have downgraded to 0.15.0 for now. I may either fork the library, or do some upgrade work. Upgrading to the new API was quite easy, but the tests have to be re-written. See https://github.com/binwiederhier/ntfy/pull/568 for a WIP

    ๐Ÿชฒ bug server 
    opened by binwiederhier 0
Philipp C. Heckel
Principal Engineer at @datto, open source fan, semi-regular blogger, former author of @syncany, German ๐Ÿ‡ฉ๐Ÿ‡ช, fan of ๐Ÿ‡ฌ๐Ÿ‡ง & ๐Ÿ‡บ๐Ÿ‡ธ, and a dad ๐Ÿ‘ฆ
Philipp C. Heckel
โšก HTTP/2 Apple Push Notification Service (APNs) push provider for Go โ€” Send push notifications to iOS, tvOS, Safari and OSX apps, using the APNs HTTP/2 protocol.

APNS/2 APNS/2 is a go package designed for simple, flexible and fast Apple Push Notifications on iOS, OSX and Safari using the new HTTP/2 Push provide

Adam Jones 2.7k Jan 1, 2023
golang long polling library. Makes web pub-sub easy via HTTP long-poll server :smiley: :coffee: :computer:

golongpoll Golang long polling library. Makes web pub-sub easy via an HTTP long-poll server. New in v1.1 Deprecated CreateManager and CreateCustomMana

J Cuga 620 Jan 6, 2023
Simple synchronous event pub-sub package for Golang

event-go Simple synchronous event pub-sub package for Golang This is a Go language package for publishing/subscribing domain events. This is useful to

itchyny 19 Jun 16, 2022
Simple-messaging - Brokerless messaging. Pub/Sub. Producer/Consumer. Pure Go. No C.

Simple Messaging Simple messaging for pub/sub and producer/consumer. Pure Go! Usage Request-Response Producer: consumerAddr, err := net.ResolveTCPAddr

IchHabeKeineNamen 1 Jan 20, 2022
A simple in-process pub/sub for golang

go-pub-sub A simple in-process pub/sub for golang Motivation Call it somewhere between "I spent no more than 5 minutes looking for one that existed" a

Ryan Catherman 0 Jan 25, 2022
nanoQ โ€” high-performance brokerless Pub/Sub for streaming real-time data

nanoQ โ€” high-performance brokerless Pub/Sub for streaming real-time data nanoQ is a very minimalistic (opinionated/limited) Pub/Sub transport library.

Aigent 149 Nov 9, 2022
A basic pub-sub project using NATS

NATS Simple Pub-Sub Mechanism This is a basic pub-sub project using NATS. There is one publisher who publishes a "Hello World" message to a subject ca

Prosonul Haque 1 Dec 13, 2021
Kafka, Beanstalkd, Pulsar Pub/Sub framework

go-queue Kafka, Beanstalkd, Pulsar Pub/Sub framework.

chenquan 3 Sep 17, 2022
CLI tool for generating random messages with rules & publishing to the cloud services (SQS,SNS,PUB/SUB and etc.)

Randomsg A CLI tool to generate random messages and publish to cloud services like (SQS,SNS,PUB/SUB and etc.). TODO Generation of nested objects is no

Kerem Dokumacฤฑ 6 Sep 22, 2022
Go-notification - Realtime notification system with golang

Realtime notification system Used Apache kafka gRPC & PROTOBUF MongoDB restapi w

vishalvishnu 3 Aug 19, 2022
Bark is an iOS App which allows you to push customed notifications to your iPhone.

Bark is an iOS App which allows you to push customed notifications to your iPhone.

Feng 1.6k Jan 3, 2023
Github-notifications - Small script to alert me when I have notifications on Github. I use it in my Polybar conf

Github notification polybar widget This tool is meant to be used with Polybar, in order to let the user know when they have notifications on Github. R

Ghislain Rodrigues 1 Jan 26, 2022
cisasntyi: check iphone stock and send notification to your iphone

for buy iphone 13 notification cisasntyi: check iphone stock and send notification to your iphone install Bark app in your iphone first before you run

seaZhang 45 Aug 3, 2022
Send slack notifications using Github action

Slack notification This is a simple Slack notification action which runs using a Bot token. Example Action A simple example on how to use this action:

Gergely Brautigam 12 Aug 9, 2021
Golang tool to send notifications to LINE app

Golang tool to send notifications to LINE app

Muhammad Daffa 2 Nov 9, 2022
Uniqush is a free and open source software system which provides a unified push service for server side notification to apps on mobile devices.

Homepage Download Blog/News @uniqush Introduction Uniqush (\หˆyรผ-nษ™-kuฬ‡sh\ "uni" pronounced as in "unified", and "qush" pronounced as in "cushion") is

Uniqush 1.5k Jan 9, 2023
Chanify is a safe and simple notification tools. This repository is command line tools for Chanify.

Chanify is a safe and simple notification tools. For developers, system administrators, and everyone can push notifications with API.

Chanify 979 Dec 29, 2022
Simple push notification system (android/fcm, apns/slideshow) written by Golang

Golang Push Notification Simple system push notification for android/fcm and apn

Hoร ng Hแบฃi 0 Dec 20, 2021
Arjuns-urgent-notification-backend - A simple Golang app that handles form JSON POST requests

Arjun's Urgent Notification Backend This is intended to let people urgently noti

Kome Fumi 0 Jan 7, 2022