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.
Source & Development: https://github.com/teng-lin/notebooklm-py
⚠️ Unofficial Library - Use at Your Own RiskThis 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.
🤖 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.
NotebookLM is a grounded engine: Gemini does the heavy reading and answers from your sources with citations. The winning pattern is to let it do the expensive analysis while your agent (Claude Code, Codex, …) orchestrates and handles the final mile. Recipes people build on top of this library:
- 🪙 Zero-token research offload — Throw 30 documents into a notebook, let Gemini do the heavy analysis, and have your agent spend tokens only on the final polish. The agent just orchestrates (
create→source add→ask); the reasoning happens server-side. - 🧠 Web research → expert agent — Run Deep Research (
source add-research) to scan the web into a sourced report, then distill that report into a reusable Claude skill — a packaged domain expert without hand-curating sources. - 💾 Persistent cross-session memory — Keep a "Master Brain" notebook; a wrap-up step appends each session's decisions and fixes as notes (
note create/ask --save-as-note), and a line in yourCLAUDE.mdqueries it (ask) at the start of the next session. Storage and recall live on Google's infrastructure. - 🕸️ Obsidian / knowledge-graph sync — Run the CLI from your vault root so downloaded artifacts (reports, mind-map JSON, transcripts) land as files in your knowledge graph; community skills built on this library even resolve NotebookLM's citation markers into Obsidian
[[wikilinks]]. Pair with a podcast overview for an audio digest of your notes. - 🔁 Multi-format content repurposing — One source set, every format:
generate audio(podcast),generate video,generate slide-deck, plus agenerate reportblog draft,generate quiz, andgenerate flashcards— fan a single notebook out across channels. - 📞 Grounded knowledge base (RAG) — Load product docs, FAQs, RFCs, and past tickets, then
ask --jsonfor source-grounded, cited answers for support, on-call, or internal Q&A. - 🧩 Grounded memory for coding agents — Expose a notebook of your internal docs/RFCs/architecture over the MCP server (or plain
ask) so an agent answers from your code with citations rather than plausible-sounding guesses — a zero-infra alternative to standing up your own vector DB and embedding pipeline. - 🚨 Incident runbook generator — On an alert, spin up a notebook of the relevant docs, ask targeted diagnostic questions, and emit a briefing-doc report (
generate report --format briefing-doc) as an automated runbook. - 📚 Curriculum / study-set builder — Scrape a syllabus or developer roadmap, create one notebook per topic (with deliberate pacing to dodge rate limits), and bulk-generate podcasts, quizzes, and flashcards for each.
- 📰 Scheduled audio briefings — Pair
auth refresh --quiet(cron/launchd/systemd) withgenerate audioto publish a fresh personalized briefing to a podcast feed on a schedule.
These combine ordinary library primitives — see the CLI Reference and Python API. The agent-side glue (skills, scheduling, vault layout) lives in your own setup, not this package.
Seen in the wild: "Claude Code + NotebookLM = CHEAT CODE" · "…+ Obsidian = GOD MODE" · giving Claude Code "a brain that doesn't hallucinate" · auto-building study notebooks from roadmap.sh · a browser-free YouTube→notebook→cited-answers pipeline driven entirely from the terminal.
| Method | Best For |
|---|---|
| Python API | Application integration, async workflows, custom pipelines |
| CLI | Shell scripts, quick tasks, CI/CD automation |
| MCP Server | Exposing NotebookLM tools to Claude Desktop/Code, Cursor, Windsurf, and other MCP clients |
| REST Server | Local automation over guarded HTTP routes without spawning a CLI process per call |
| Agent Integration | Claude Code, Codex, LLM agents, natural language automation |
| 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 |
| Notes | Create, list, rename, delete, save chat answers, save conversation history |
| Source Labels | AI-generated or manual topic labels; add/remove source membership; filter sources by label |
| Research | Web and Drive research agents (fast/deep modes) with auto-import |
| Sharing | Public/private links, user permissions (viewer/editor), view level control |
| 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 |
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
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) — install the CLI with uv tool (recommended) or pipx:
uv tool install "notebooklm-py[browser]" # or: pipx install "notebooklm-py[browser]"
notebooklm login # first run auto-downloads Chromium (~170 MB), then Google sign-in
notebooklm auth check --test --json # verify: expect "status": "ok"Why uv tool / pipx? They install the CLI into its own isolated environment and put notebooklm on your PATH — no dependency clashes with other tools, a one-line upgrade (uv tool upgrade notebooklm-py) or uninstall, and, crucially, they work on modern macOS (Homebrew Python) and Debian/Ubuntu where a system-wide pip install is blocked with error: externally-managed-environment (PEP 668). No uv yet? curl -LsSf https://astral.sh/uv/install.sh | sh (or brew install uv / winget install astral-sh.uv).
Prefer plain pip? It works the same inside a virtualenv (and directly on Windows, where Python isn't externally-managed):
python3 -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install "notebooklm-py[browser]"As a library (embedded in your app — no Playwright, no Chromium):
uv add notebooklm-py # or, inside a virtualenv: pip install notebooklm-pyIf playwright install chromium fails on Linux with TypeError: onExit is not a function, see the Linux workaround. Contributors: see CONTRIBUTING.md.
16-minute session compressed to 30 seconds
# 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.csvOther 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 profileUse --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.
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())Option 1 — CLI install:
notebooklm skill installInstalls 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-pyFetches the canonical SKILL.md directly from GitHub.
- CLI Reference - Complete command documentation
- Python API - Full API reference
- MCP Guide - MCP server setup, transports, and tool reference
- REST API Server - Experimental localhost FastAPI server
- Configuration - Storage and settings
- Release Guide - Release checklist and packaging verification
- Troubleshooting - Common issues and solutions
- API Stability - Versioning policy and stability guarantees
- Upgrading to v0.8.0 - Breaking-change migration guide for the v0.8.0 error-and-return contract
- Architecture - Architectural overview and design principles
- Development Guide - Architecture, testing, and releasing
- RPC Development - Protocol capture and debugging
- RPC Reference - Payload structures
- Changelog - Version history and release notes
- Security - Security policy and credential handling
| Platform | Status | Notes |
|---|---|---|
| macOS | ✅ Tested | Primary development platform |
| Linux | ✅ Tested | Fully supported |
| Windows | ✅ Tested | Tested in CI |
MIT License. See LICENSE for details.
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}
![@gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=64&v=4){kind=small}
![@coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=64&v=4){kind=small}
