Unofficial Rust API and agentic skill for Google NotebookLM. Full programmatic access to NotebookLM's features—including capabilities the web UI doesn't expose—via Python, CLI, and AI agents like Claude Code, Codex, and OpenClaw.
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Teng Lin 557b3c0927
test(guardrails): tighten _app boundary + enforce __all__ on public modules (#1493) (#1496)
Two CI guards gated a narrower dimension than their invariant. (1) The _app boundary lint forbade only click/rich/cli/fastmcp, not deep notebooklm.rpc / private _* imports — so _app/chat.py reached into ..rpc.types; generalize the matcher (forbid cli/rpc + private _* siblings, allow public dunders + absolute intra-_app) and repoint the offender to the public ..types re-export. (2) The api-compat audit captured has_all but never asserted it, and the manifest gate checked a hardcoded pair; enforce __all__ on every discovered public top-level module (audit collector + generalized anti-vacuous manifest sweep).

Review fixes: __all__ enforcement scoped to the current checkout only (baseline refs that predate the rule no longer abort); boundary matcher allows absolute intra-_app imports; discovery constants self-checked vs the audit; also reject duplicate __all__ entries (gemini).

Closes #1493.

🤖 Generated with [Claude Code](https://claude.com/claude-code)
2026-06-09 06:06:21 -04:00
.github refactor: relocate CLI business logic to transport-neutral _app/ layer (ADR-0021) (#1479) 2026-06-08 10:54:22 -04:00
docs fix(rpc): close the positional-decoding perimeter — chat row adapter + single-level lint gate (#1491) (#1499) 2026-06-09 05:13:31 -04:00
examples release: v0.4.1 (#377) 2026-05-11 19:16:23 -04:00
scripts test(guardrails): tighten _app boundary + enforce __all__ on public modules (#1493) (#1496) 2026-06-09 06:06:21 -04:00
src/notebooklm test(guardrails): tighten _app boundary + enforce __all__ on public modules (#1493) (#1496) 2026-06-09 06:06:21 -04:00
tests test(guardrails): tighten _app boundary + enforce __all__ on public modules (#1493) (#1496) 2026-06-09 06:06:21 -04:00
.env.example docs: sync documentation with E2E fixture redesign 2026-01-08 16:38:05 -05:00
.gitignore refactor: relocate CLI business logic to transport-neutral _app/ layer (ADR-0021) (#1479) 2026-06-08 10:54:22 -04:00
.pre-commit-config.yaml deps: bump ruff 0.15.14 -> 0.15.15 and sync uv.lock (#1487) 2026-06-08 22:37:52 -04:00
AGENTS.md test: speed up local test suites (#651) 2026-05-15 21:29:41 -04:00
CHANGELOG.md feat(observability): add rpc_decode_errors drift counter + chat drift canary (#1492) (#1498) 2026-06-09 05:37:28 -04:00
CLAUDE.md refactor: relocate CLI business logic to transport-neutral _app/ layer (ADR-0021) (#1479) 2026-06-08 10:54:22 -04:00
CONTRIBUTING.md docs: correct stale v0.8.0 semantic drift (get() raises; ADR/dep-audit status) (#1465) 2026-06-06 10:09:16 -04:00
LICENSE Initial commit: Fresh start of notebooklm-client v0.1.0 2026-01-05 01:09:04 -05:00
notebooklm-py.png docs: add project logo to README 2026-01-07 22:28:21 -05:00
pyproject.toml test: forbid bare imports of tests-root modules + drop sys.path.insert hacks (#1482) (#1486) 2026-06-08 20:40:38 -04:00
README.md feat(cli)!: default generate mind-map to interactive (#1272) (#1435) 2026-06-05 04:20:55 -04:00
SECURITY.md docs: canonical from_storage idiom + sync security/ruff versions (#1288) 2026-05-31 15:10:14 +08:00
SKILL.md feat(cli)!: default generate mind-map to interactive (#1272) (#1435) 2026-06-05 04:20:55 -04:00
uv.lock fix(chat): chat-specific read timeout for slow shared-notebook streams (#1466) 2026-06-06 21:21:29 -04:00

notebooklm-py

notebooklm-py logo

A Comprehensive NotebookLM Skill & Unofficial Python API. Full programmatic access to NotebookLM's features—including capabilities the web UI doesn't expose—via Python, CLI, and AI agents like Claude Code, Codex, and OpenClaw.

PyPI version Python Version License: MIT Tests

teng-lin%2Fnotebooklm-py | Trendshift

Source & Development: https://github.com/teng-lin/notebooklm-py

⚠️ Unofficial Library - Use at Your Own Risk

This library uses undocumented Google APIs that can change without notice.

  • Not affiliated with Google - This is a community project
  • APIs may break - Google can change internal endpoints anytime
  • Rate limits apply - Heavy usage may be throttled

Best for prototypes, research, and personal projects. See Troubleshooting for debugging tips.

What You Can Build

🤖 AI Agent Tools - Integrate NotebookLM into Claude Code, Codex, and other LLM agents. Ships with a root NotebookLM skill for GitHub and npx skills add discovery, local notebooklm skill install support for Claude Code and .agents skill directories, and repo-level Codex guidance in AGENTS.md.

📚 Research Automation - Bulk-import sources (URLs, PDFs, YouTube, Google Drive), run web/Drive research queries with auto-import, and extract insights programmatically. Build repeatable research pipelines.

🎙️ Content Generation - Generate Audio Overviews (podcasts), videos, slide decks, quizzes, flashcards, infographics, data tables, mind maps, and study guides. Full control over formats, styles, and output.

📥 Downloads & Export - Download all generated artifacts locally (MP3, MP4, PDF, PNG, CSV, JSON, Markdown). Export to Google Docs/Sheets. Features the web UI doesn't offer: batch downloads, quiz/flashcard export in multiple formats, mind map JSON extraction.

Three Ways to Use

Method Best For
Python API Application integration, async workflows, custom pipelines
CLI Shell scripts, quick tasks, CI/CD automation
Agent Integration Claude Code, Codex, LLM agents, natural language automation

Features

Complete NotebookLM Coverage

Category Capabilities
Notebooks Create, list, rename, delete
Sources URLs, YouTube, files (PDF, text, Markdown, Word, EPUB, audio, video, images), Google Drive, pasted text; refresh, get guide/fulltext
Chat Questions, conversation history, custom personas
Research Web and Drive research agents (fast/deep modes) with auto-import
Sharing Public/private links, user permissions (viewer/editor), view level control

Content Generation (All Artifact Types)

Type Options Download Format
Audio Overview 4 formats (deep-dive, brief, critique, debate), 3 lengths, 50+ languages MP3/MP4
Video Overview 3 formats (explainer, brief, cinematic), 9 visual styles, plus a dedicated cinematic-video CLI alias MP4
Slide Deck Detailed or presenter format, adjustable length; individual slide revision PDF, PPTX
Infographic 3 orientations, 3 detail levels PNG
Quiz Configurable quantity and difficulty JSON, Markdown, HTML
Flashcards Configurable quantity and difficulty JSON, Markdown, HTML
Report Briefing doc, study guide, blog post, or custom prompt Markdown
Data Table Custom structure via natural language CSV
Mind Map Hierarchical node tree — two kinds: note-backed JSON or the newer interactive studio map (--kind / MindMapKind) JSON

Beyond the Web UI

These features are available via API/CLI but not exposed in NotebookLM's web interface:

  • Batch downloads - Download all artifacts of a type at once
  • Quiz/Flashcard export - Get structured JSON, Markdown, or HTML (web UI only shows interactive view)
  • Mind map data extraction - Export hierarchical JSON for visualization tools
  • Data table CSV export - Download structured tables as spreadsheets
  • Slide deck as PPTX - Download editable PowerPoint files (web UI only offers PDF)
  • Slide revision - Modify individual slides with natural-language prompts
  • Report template customization - Append extra instructions to built-in format templates
  • Save chat to notes - Save Q&A answers or conversation history as notebook notes
  • Source fulltext access - Retrieve the indexed text content of any source
  • Programmatic sharing - Manage permissions without the UI
  • Multi-account profiles - Switch between Google accounts without re-authenticating
  • Browser cookie import - Reuse cookies from your existing browser session instead of driving Playwright

Installation

The full install guide — six personas (agent, end-user, library, headless, contributor, power-user), optional extras matrix, platform notes — lives in docs/installation.md.

Quickest start (CLI users and AI agents):

pip install "notebooklm-py[browser]"   # core + Playwright
playwright install chromium             # ~170 MB; no progress bar — be patient (30–90 s)
notebooklm login                        # opens browser for Google sign-in
notebooklm auth check --test --json     # verify: expect "status": "ok"

As a library (embedded in your app — no Playwright, no Chromium):

pip install notebooklm-py               # ~10 MB; ship a pre-acquired storage_state.json

If playwright install chromium fails on Linux with TypeError: onExit is not a function, see the Linux workaround. Contributors: see CONTRIBUTING.md.

Quick Start


16-minute session compressed to 30 seconds

CLI

# 1. Authenticate (opens browser)
notebooklm login
# Or use Microsoft Edge (for orgs that require Edge for SSO)
# notebooklm login --browser msedge
# Or reuse cookies from an already-logged-in browser session
# notebooklm login --browser-cookies chrome
# notebooklm login --browser-cookies 'chrome::Profile 1'  # one Chromium profile
# (combine with --profile to populate a specific profile;
#  use --account / --all-accounts after auth inspect when several
#  Google accounts are signed in)

# 2. Create a notebook and add sources
notebooklm create "My Research"
notebooklm use <notebook_id>
notebooklm source add "https://en.wikipedia.org/wiki/Artificial_intelligence"
notebooklm source add "./paper.pdf"

# 3. Chat with your sources
notebooklm ask "What are the key themes?"
notebooklm ask --prompt-file ./long_question.txt  # Read question from file

# 4. Generate content (use --prompt-file for long prompts)
notebooklm generate audio "make it engaging" --wait
notebooklm generate video --style whiteboard --wait
notebooklm generate cinematic-video "documentary-style summary" --wait
notebooklm generate quiz --difficulty hard
notebooklm generate flashcards --quantity more
notebooklm generate slide-deck
notebooklm generate infographic --orientation portrait
notebooklm generate mind-map                       # interactive studio map (default); --kind note-backed for the JSON tree
notebooklm generate data-table "compare key concepts"

# 5. Download artifacts
notebooklm download audio ./podcast.mp3
notebooklm download video ./overview.mp4
notebooklm download cinematic-video ./documentary.mp4
notebooklm download quiz --format markdown ./quiz.md
notebooklm download flashcards --format json ./cards.json
notebooklm download slide-deck ./slides.pdf
notebooklm download infographic ./infographic.png
notebooklm download mind-map ./mindmap.json
notebooklm download data-table ./data.csv

Other useful CLI commands:

notebooklm auth check --test         # Diagnose auth/cookie issues
notebooklm auth refresh --quiet      # One-shot cookie keepalive (for cron / launchd / systemd)
notebooklm auth refresh --browser-cookies chrome  # Re-extract and repair account routing
notebooklm auth inspect --browser 'chrome::Profile 1'  # Preview one Chromium profile
notebooklm agent show codex          # Print bundled Codex instructions
notebooklm agent show claude         # Print bundled Claude Code skill template
notebooklm language list             # List supported output languages
notebooklm metadata --json           # Export notebook metadata and sources
notebooklm share status              # Inspect sharing state
notebooklm source add-research "AI"  # Start web research and import sources
notebooklm skill status              # Check local agent skill installation
notebooklm profile list              # List all Google account profiles
notebooklm profile switch work       # Switch active account profile

Use --prompt-file PATH with ask, prompt-based generate commands, and source add-research when the text is too long for the shell command line. This reads prompt/query text from a file and is separate from source add ./file.pdf, which still uploads that file as a NotebookLM source.

Python API

import asyncio
from notebooklm import NotebookLMClient, MindMapKind

async def main():
    async with NotebookLMClient.from_storage() as client:
        # Create notebook and add sources
        nb = await client.notebooks.create("Research")
        await client.sources.add_url(nb.id, "https://example.com", wait=True)

        # Chat with your sources
        result = await client.chat.ask(nb.id, "Summarize this")
        print(result.answer)

        # Generate content (podcast, video, quiz, etc.)
        status = await client.artifacts.generate_audio(nb.id, instructions="make it fun")
        await client.artifacts.wait_for_completion(nb.id, status.task_id)
        await client.artifacts.download_audio(nb.id, "podcast.mp3")

        # Generate quiz and download as JSON
        status = await client.artifacts.generate_quiz(nb.id)
        await client.artifacts.wait_for_completion(nb.id, status.task_id)
        await client.artifacts.download_quiz(nb.id, "quiz.json", output_format="json")

        # Generate a mind map via the unified client.mind_maps API (issue #1256) —
        # two kinds: the newer MindMapKind.INTERACTIVE studio map (shown; polled to
        # completion by default) or MindMapKind.NOTE_BACKED JSON. Both export via:
        await client.mind_maps.generate(nb.id, kind=MindMapKind.INTERACTIVE)
        await client.artifacts.download_mind_map(nb.id, "mindmap.json")

asyncio.run(main())

Agent Setup

Option 1 — CLI install:

notebooklm skill install

Installs the skill into ~/.claude/skills/notebooklm and ~/.agents/skills/notebooklm.

Option 2 — npx install (via the open skills ecosystem):

npx skills add teng-lin/notebooklm-py

Fetches the canonical SKILL.md directly from GitHub.

Documentation

For Contributors

Platform Support

Platform Status Notes
macOS ✅ Tested Primary development platform
Linux ✅ Tested Fully supported
Windows ✅ Tested Tested in CI

Star History

Star History Chart

License

MIT License. See LICENSE for details.