---
name: list_obsidian_notes
kind: function
lang: py
domain: obsidian
version: "1.0.0"
purity: impure
signature: "list_obsidian_notes(vault_dir: str, subfolder: str = \"\", tag: str = \"\") -> list"
description: "Recorre recursivamente un vault de Obsidian (o un subfolder) y devuelve los paths absolutos de todas las notas .md, ordenados. Excluye siempre .obsidian/ y .trash/. Si se da tag, filtra a las notas cuyo frontmatter tags lo contenga (usa parse_obsidian_frontmatter)."
tags: [obsidian, notes, list, vault, frontmatter, filesystem]
uses_functions: ["parse_obsidian_frontmatter_py_obsidian"]
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: ["os"]
params:
  - name: vault_dir
    desc: "path (absoluto o relativo) a la raiz del vault de Obsidian"
  - name: subfolder
    desc: "subcarpeta relativa dentro del vault a la que restringir el recorrido; vacio recorre todo el vault"
  - name: tag
    desc: "tag opcional; si no es vacio, solo devuelve notas cuyo frontmatter tags lo contenga (lista o escalar)"
output: "lista ordenada de paths absolutos a las notas .md que cumplen el filtro"
tested: false
tests: []
test_file_path: ""
file_path: "python/functions/obsidian/list_obsidian_notes.py"
---

## Ejemplo

```python
from obsidian import list_obsidian_notes

# Todas las notas de un vault real
notas = list_obsidian_notes("/home/enmanuel/Obsidian/Finanzas")
print(len(notas), notas[:3])

# Solo las notas etiquetadas con #inversion
inversion = list_obsidian_notes("/home/enmanuel/Obsidian/Finanzas", tag="inversion")

# Restringir a una subcarpeta del vault
plantillas = list_obsidian_notes("/home/enmanuel/Obsidian/Finanzas", subfolder="Plantillas")
```

## Cuando usarla

Cuando necesites enumerar las notas de un vault de Obsidian (para indexar, exportar, contar o alimentar otra funcion) o filtrar por tag sin abrir Obsidian. Es el punto de entrada antes de leer/buscar contenido nota a nota.

## Gotchas

- **Impura**: lee el filesystem. Lanza `FileNotFoundError` si la ruta no existe y `NotADirectoryError` si no es un directorio.
- **Exclusion obligatoria**: `.obsidian/` y `.trash/` se podan del `os.walk` y nunca aparecen en el resultado; los `.md` internos de la config de Obsidian no se listan.
- **Coste en vaults grandes**: recorre todo el arbol. En vaults pesados como `NotasDeObsidian` (~554M) el `os.walk` completo es costoso; usa `subfolder` para acotar cuando puedas.
- **Filtro por tag**: cuando `tag` esta dado, ABRE cada nota para parsear su frontmatter — multiplica el coste de I/O. El campo `tags` se acepta como lista (`[a, b]`) o escalar (`a`); notas sin frontmatter o sin el tag se excluyen.
- Las notas con encoding invalido se leen con `errors="replace"`; el frontmatter ilegible se trata como ausente (la nota se excluye del filtro por tag).
