How to use ROAM_TAGS and/or tags?

Long-time (though not sophisticated) emacs &org-mode user here.

In the docs, screencaps, etc. I see two formats of file-level tags: #+ROAM_TAGS and - tags :: . How are they different and how should they be used?

In particular, how would I search for all files with a given tag?

With thanks and best wishes



The former is a new feature, and is real tag support. See the docs for the use cases, etc.

The latter is just a convention to list org-roam links.

Searching for “ROAM_TAGS” returns “No matching documents”. Where are the docs you mean?

2 Likes mentions ROAM_TAGS briefly but does not describe usage.

Perhaps I should have said in my OP what I had seen in the docs.


How do I search for all files with a given tag?

AFAICT this usage is not described anywhere (including github repo, generated docs, readthedocs site, blogs).


If you have tags, they should show up in the minibuffer completions as such:

allowing you to filter for them.

1 Like

I just setup org-roam to use all-directories on tags for extraction, @jethro, but I don’t see the filtering you demonstrate.

Do I need to do something for org-roam to extract tags from existing notes?


You’ll probably need to clear your cache and rebuild (if you changed your tag sources), since unmodified files don’t get checked again

I got it working. I think I may have run into the straight/doom melpa update bug that periodically bites me.

Thanks. I’ll give it a go this weekend.

Do you mean #+ROAM_TAGS tags, - tags :: or plain old org-mode #+FILETAGS: tags?

The filtering functionality is enabled by the tagging functionality from #+ROAM_TAGS, but that’s not the only way to add tags.

-tags :: has no special meaning, those are just regular backlinks.

#+FILETAGS: is not used by Org-roam.

1 Like

So what are the other ways to add tags?

The 3 default supported means are mentioned in the docs:

1 Like

Thanks, so by default #+ROAM_TAGS is the only way to add tags. I’m not interested in using directory structure for tagging.

I’d be interested to know why you don’t use #+FILETAGS:.

Is there a way to do boolean tag searches, like

websites AND javascript


websites OR javascript


1 Like

If you use a completion engine like Ivy, I think it allows regex searches, so yes, if you really wanted to now. Will need to otherwise design a good UX for tag/link filtering first.

I was thinking of of just repurposing org-mode’s existing tag system, but now that you mention it, it doesn’t do completion while you’re building a boolean search. Over thousands of org-roam notes, I can imagine that this could become almost necessary.

I am only exploring this feature, and so far I love it. I use it for categorisation (when it’s really needed) of notes. On the contrary, I use plain org tags for agenda searches.

As example, when I create a note for a person it usually contains roam tag “Person” and this persons name as a file tag (so all todos in this file are tagged with this persons name). Now in other places I can tag tasks with this persons name. So as a result I am able to use org agenda to search for stuff related to this person. As additional bonus all tasks from the person file also have a category with this name (I have a helper that properly reads category from roam files, e.g. trims the id).

So roam tag is not used in agenda, but when I see a note in the list, I clearly understand that it’s about some person :slight_smile:

BTW, in order to save me manual editing of roam tags, I’ve create two helpers for adding and removing them. You can find it on GitHub.


Are you talking about #+ROAM_TAGS: format ?

Yes, exactly.