notebooklm-py

Supports Claude Code, Codex, Mcp

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-py

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

Authentication & Access

Flexible auth for local dev, headless servers, and multi-tenant setups:

• Three ways to get cookies - Interactive Playwright login (default), import from an already-signed-in browser (login --browser-cookies chrome, no Playwright), or a durable master token.
• Master-token auth - Mints fresh web cookies on demand with no per-session browser (login --master-token --account you@example.com), so it self-heals expired sessions unattended — the auth model for servers, CI, and the remote MCP connector (claude.ai / ChatGPT).
• Multi-account profiles - Switch between Google accounts without re-authenticating.

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.

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" --import-all  # web research + import found 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:
        mm = await client.mind_maps.generate(nb.id, kind=MindMapKind.INTERACTIVE)
        await client.artifacts.download_mind_map(nb.id, "mindmap.json", mm.id)

asyncio.run(main())

Beyond the Web UI

Programmatic, batch, and local-file capabilities the API/CLI make easy — several in richer formats, or at a scale, than clicking through the web app:

• Batch downloads - Download all artifacts of a type at once
• Quiz/Flashcard export - Get structured JSON, Markdown, or HTML files
• Mind map data extraction - Export hierarchical JSON for visualization tools
• Data table CSV export - Download structured tables as spreadsheets
• Slide deck as PPTX or PDF - Download editable PowerPoint or PDF files
• Slide revision - Modify individual slides with natural-language prompts
• Report template customization - Append extra instructions to built-in format templates
• Save chat history to notes - Persist a whole Q&A conversation (not just a single answer) as a notebook note
• Source fulltext access - Retrieve the indexed text content of any source
• Programmatic sharing - Manage permissions without the UI