Skip to main content

notefeed

Post and read markdown notes on a notefeed server from Python or the command line. Python 3.11 or newer.

pip install notefeed
export NOTEFEED_URL=https://notes.example.com NOTEFEED_FEED=homelab-7f3k2q9x4m8wz
notefeed post "# Backup finished"
backup.sh 2>&1 | notefeed post -
notefeed notes --limit 5
notefeed edit Vq3xH8mTn2KfLw0aZr9bYe "# Backup finished, verified"
notefeed delete Vq3xH8mTn2KfLw0aZr9bYe
from notefeed import Client

client = Client("https://notes.example.com", feed="homelab-7f3k2q9x4m8wz")  # password="..." if the instance has one
created = client.post("# Deploy done\nversion 1.4.2")
print(created.url, created.read_url)
for note in client.notes():  # newest first, page by page
    print(note.date, note.title)

read_url is None for a feed without a read link (rare; see the operations docs).

Every note has a date, now unless you give one: client.post(text, date="2025-03-01T09:30:00Z") (a timezone-aware datetime, a date for midnight UTC, or an ISO 8601 string; any time from 1970 to 9999), or notefeed post "…" --date 2025-03-01. The note takes its place in the feed by that date. A date in the future schedules the note: readers see it from then on. client.update(id, date=...) (notefeed update <id> --date …) moves a note.

A note posted with draft=True (notefeed post "…" --draft) is a draft: readers don't see it, or its pictures, until client.update(id, draft=False) (notefeed update <id> --publish) publishes it at its date; draft=True (--draft) hides it again.

Where the operator took a post down for breaking the instance's content rules, a list has a mark in its place: a note whose removed is True (absent, it is UNSET), type_ application/x-notefeed-removed, the removed note's id and date, no content and file_url None. Getting it alone or editing it raises NotFoundError (code removed, 410), and so does the removed note's id after the mark is gone; client.delete(id) (notefeed delete <id>) takes the mark off the feed, and the note does not come back.

Client.from_env() reads NOTEFEED_URL / NOTEFEED_FEED / NOTEFEED_PASSWORD; so does the notefeed command, unless given --url / --feed / --password.

A feed can have its own password, which gates reading, listing and posting to it. Pass feed_password="..." to Client(...) (or per call, e.g. client.post(text, feed_password=...)), or set NOTEFEED_FEED_PASSWORD, which from_env() and the notefeed command both read (there is deliberately no flag, so it stays out of shell history). It is sent as X-Feed-Password; Authorization stays the instance password. A feed password is 1 to 256 printable ASCII characters with no space at the start or end; an empty one is the same as none.

A posted note can be changed or removed: client.edit(id, content) replaces its content and returns the note (its id and URLs stay), and client.delete(id) removes it. Both take the same feed and feed_password arguments as post, and a missing note is a NotFoundError. notefeed edit <id> <text | - | --file PATH> prints the note URL; notefeed delete <id> prints nothing. Anyone who can post to a feed can edit and delete its notes, and deleting is permanent.

A feed can have a title and a description, and can be deleted: client.feed_info() returns the feed (name, title, description, protected, read_url), client.update_feed(title, description) replaces both (an empty string clears one) and returns the feed, and client.delete_feed() removes the feed with all its notes for good. All three take the same feed and feed_password arguments as post, and a feed that doesn't exist is a NotFoundError. Anyone who can post to a feed can do this, and deleting is permanent; there are no notefeed commands for it.

A picture is a note of its own: client.post(data, type="image/png", alt="…") takes bytes (PNG, JPEG, GIF or WebP) and returns what a markdown post returns, with the picture's file and file_url added. Write ![](file) in a markdown note to show it; the feed is created by its first note, a picture that is too large is a NoteTooLargeError, and an instance that takes no pictures (NOTEFEED_IMAGE_UPLOADS=0) answers every picture with an ImagesOffError. The server checks the bytes against the declared type. client.update(id, title=..., alt=..., tags=[...], date=...) changes a note's title, a picture's alt text, a note's tags (the whole list; notefeed update <id> --tags a,b) or its date, and client.edit(id, content) replaces its content. client.update_feed(title, description, image=file) makes a picture the feed's title image (image="" removes it; leaving image out keeps it). notefeed post --file photo.png posts a file (the type comes from the extension, or --type). To post a note with its pictures in one call, client.post(text, attachments=[Attachment("chart.png", data, "image/png")]) posts them with the text in one request, and the server swaps ![](chart.png) for each file name (None content posts only the pictures) (notefeed post "…" --attach chart.png does the same); nothing is posted when one is refused. Send pictures full size (up to 10 MiB by default): the server stores each one turned upright, at most 2560 px on its long side and without metadata such as EXIF or GPS position, and a busy server answers a RateLimitedError with retry_after. Pictures are public to anyone with the feed's read link.

Full documentation: https://docs.notefeed.me/integrations/clients/

Metadata

Release files for notefeed 0.34.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for notefeed 0.34.0
File Size Uploaded Provenance Actions
notefeed-0.34.0.tar.gz 57.8 kB With provenance Details for notefeed-0.34.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for notefeed 0.34.0
File Interpreter ABI Platform Actions
notefeed-0.34.0-py3-none-any.whl Python 3 none any Details for notefeed-0.34.0-py3-none-any.whl

Total release size: 139.4 kB

Release files / notefeed-0.34.0.tar.gz

Download URL notefeed-0.34.0.tar.gz
Size 57.8 kB
Tags Source
SHA-256 checksum
How to use checksums
6fdedd70489d9323f29ef5060aa6c7469ce8a4b1a40ee004aa0f9763dad9b24b
BLAKE2b-256 checksum
How to use checksums
ce0e35f43d0661c350c7427ed0212ea18b193b725e56a977c0368237164fb173
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

Release files / notefeed-0.34.0-py3-none-any.whl

Download URL notefeed-0.34.0-py3-none-any.whl
Size 81.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
291c52faa7730f45fa5f3dcdd5953d4361b2cee22bb359e140d1902453aa7a8a
BLAKE2b-256 checksum
How to use checksums
7a43679a7405ec5ab1133e560decf84890cbf83e3584852099dad3ad8220983d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

Security for notefeed 0.34.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for notefeed-0.34.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.34.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page