Stop Fighting NotebookLM's Web UI! Use notebooklm-py Instead

Stop Fighting NotebookLM's Web UI! Use notebooklm-py Instead

What if I told you that Google NotebookLM has secret superpowers you'll never see in your browser?

You've been there. Clicking through dozens of sources one by one. Manually copying quiz answers into Anki. Waiting for that podcast to generate, then frantically right-clicking to save the MP3 before it disappears. The web UI is beautiful, sure—but it's a cage. A gilded cage designed for casual users, not for developers who need to move fast, automate ruthlessly, and extract every drop of value from their research.

Here's the painful truth: NotebookLM's most powerful features are locked behind internal APIs that Google never exposed. Batch downloads? Not in the UI. Structured quiz exports? Nope. Editable PowerPoint files? Forget about it. You're leaving productivity on the table every single day you stay in that browser tab.

Enter notebooklm-py—the unofficial Python^{↗ Bright Coding Blog} API and agentic skill that cracks NotebookLM wide open. Built by developer Teng Lin, this isn't some brittle screen-scraper. It's a comprehensive programmatic interface that gives you full control over every NotebookLM feature, including capabilities the web interface doesn't even know exist. Python scripts, shell automation, Claude Code integration—however you work, notebooklm-py meets you there.

Ready to stop being a tourist in your own research? Let's dive into what makes this tool absolutely essential.

What is notebooklm-py?

notebooklm-py is an unofficial, community-built Python library that provides complete programmatic access to Google NotebookLM's underlying APIs. Created by Teng Lin and released under the MIT license, it represents one of the most ambitious reverse-engineering efforts in the AI productivity space.

The project sits at a fascinating intersection: Google NotebookLM has become the go-to tool for AI-powered research synthesis, generating everything from podcast-style audio overviews to interactive mind maps. Yet Google's official offering stops at the browser window. There's no public API. No webhook integrations. No way to plug it into your existing data pipelines.

Teng Lin solved this problem by doing what Google wouldn't. Through careful analysis of NotebookLM's internal RPC protocols, notebooklm-py reconstructs the full client-server conversation that powers the web application. The result? A robust, async-native Python client, a feature-complete CLI, and ready-to-deploy agent skills for Claude Code, OpenAI Codex, and the OpenClaw ecosystem.

The repository has been gaining serious traction—trending on Trendshift and accumulating stars rapidly as developers discover what's possible when NotebookLM escapes the browser. It supports Python 3.10 through 3.14, runs comprehensive CI testing across macOS, Linux, and Windows, and publishes clean releases to PyPI.

But here's what matters most: this isn't a hack that breaks next week. The project includes detailed API stability documentation, active troubleshooting guides, and transparent disclaimers about the risks of building on undocumented endpoints. It's built for production use by developers who understand those trade-offs.

Key Features That Will Blow Your Mind

The feature matrix of notebooklm-py reads like a wishlist that Google forgot to build. Let's break down what makes this tool genuinely transformative:

Complete Notebook Lifecycle Management

Every notebook operation you'd expect—create, list, rename, delete—is fully supported. But it goes deeper. You can programmatically manage source ingestion from URLs, YouTube videos, PDFs, Word documents, EPUBs, audio files, images, and even Google Drive documents. Sources can be refreshed, their full indexed text extracted, and guide materials retrieved without ever touching a mouse.

Research Agents on Autopilot

The library exposes NotebookLM's web and Drive research agents with both fast and deep modes. Want to research "quantum computing advances" and auto-import the top sources? One function call. The web research agent scours, synthesizes, and populates your notebook while you grab coffee.

Chat with Programmatic Precision

Conversations aren't trapped in the UI. You can submit questions, retrieve full conversation history, and even apply custom personas to shape how NotebookLM responds. Save chat exchanges directly as notebook notes—a workflow the web interface simply doesn't offer.

The Secret Content Generation Arsenal

This is where notebooklm-py pulls away from anything possible in the browser:

Multi-Account & Authentication Flexibility

Switch between Google work and personal accounts without re-authenticating. Import cookies directly from Chrome, Edge, or any Chromium profile. Run headless in CI/CD pipelines with pre-exported storage_state.json files. This is authentication engineering done right.

Real-World Use Cases That Justify the Switch

Still wondering if notebooklm-py solves problems you actually have? These four scenarios paint the picture:

1. The Research Pipeline Architect

You're a PhD candidate or industry researcher processing hundreds of sources weekly. With notebooklm-py, you build a pipeline: source add-research ingests web queries automatically, generate quiz creates verification tests in JSON for your spaced repetition system, and download mind-map exports structured JSON for your Obsidian knowledge graph. What took three hours of manual clicking now runs in a 12-line Python script.

2. The Content Creator's Secret Weapon

Podcast producers and YouTubers use NotebookLM for research, but the workflow is crippled by manual exports. With notebooklm-py, generate ten audio overviews in different languages overnight, batch-download all MP3s with consistent naming, and automatically upload to your CMS. The cinematic-video alias? That's your documentary B-roll generated while you sleep.

3. The Enterprise Knowledge Manager

Your organization has proprietary research locked in Google Drive. NotebookLM won't touch it without manual uploads. Deploy notebooklm-py with service account patterns, automate Drive research queries, generate slide decks in PPTX format for executive editing, and distribute via programmatic sharing with viewer/editor permission controls. The web UI doesn't even expose these sharing APIs.

4. The AI Agent Orchestrator

You're building with Claude Code or Codex and need your agent to actually use NotebookLM. The bundled SKILL.md and AGENTS.md files provide canonical instructions that LLM agents can execute. Your agent creates notebooks, adds sources from URLs you mention in conversation, generates summaries, and reports back—all without you writing integration code. Install via npx skills add and watch your agent become research-capable instantly.

Step-by-Step Installation & Setup Guide

Getting notebooklm-py running takes under five minutes. Choose your path based on how you'll use it:

Path A: CLI Users & AI Agents (Full Browser Integration)

This path includes Playwright for browser-based authentication—the most flexible setup:

# Install core package with browser dependencies
pip install "notebooklm-py[browser]"

# Download Chromium browser (~170 MB, no progress bar—be patient for 30-90 seconds)
playwright install chromium

# Authenticate via browser (opens Google sign-in)
notebooklm login

# Verify everything works—expect {"status": "ok"}
notebooklm auth check --test --json

Organization SSO tip: If your workplace mandates Microsoft Edge for authentication, use notebooklm login --browser msedge instead.

Cookie reuse shortcut: Already logged into NotebookLM in Chrome? Skip the browser pop-up entirely:

# Extract cookies from your existing Chrome session
notebooklm login --browser-cookies chrome

# Or target a specific Chromium profile
notebooklm login --browser-cookies 'chrome::Profile 1'

Path B: Library Embedding (No Browser, No Chromium)

For applications where you ship a pre-authenticated state file:

# Lightweight install (~10 MB)
pip install notebooklm-py

# Ship with a pre-acquired storage_state.json for headless operation

Path C: Linux Troubleshooting

If playwright install chromium fails with TypeError: onExit is not a function, consult the Linux workaround in the troubleshooting guide. This typically involves system dependency installation for Chromium headless execution.

Post-Install: Agent Skill Setup

For Claude Code or .agents directory integration:

# Install skill locally
notebooklm skill install

# Or discover via npx skills ecosystem
npx skills add teng-lin/notebooklm-py

Verify installation:

notebooklm skill status        # Check local installation
notebooklm agent show claude   # Preview bundled Claude Code template
notebooklm agent show codex    # Preview bundled Codex instructions

REAL Code Examples from the Repository

Let's examine actual code from the notebooklm-py repository, with detailed explanations of how to leverage each pattern.

Example 1: Complete CLI Workflow (From README)

The CLI demonstrates the full lifecycle from authentication to artifact download:

# 1. AUTHENTICATE — Opens browser for Google OAuth flow
# Alternative: --browser msedge for org SSO, or --browser-cookies chrome to reuse existing session
notebooklm login

# 2. CREATE NOTEBOOK — Returns notebook ID for subsequent commands
notebooklm create "My Research"

# 3. SELECT ACTIVE NOTEBOOK — Sets context for all following operations
notebooklm use <notebook_id>

# 4. ADD SOURCES — Mix URLs and local files seamlessly
notebooklm source add "https://en.wikipedia.org/wiki/Artificial_intelligence"
notebooklm source add "./paper.pdf"

# 5. CHAT WITH SOURCES — Natural language queries against your corpus
notebooklm ask "What are the key themes?"
# For long prompts that exceed shell limits, use --prompt-file
notebooklm ask --prompt-file ./long_question.txt

# 6. GENERATE CONTENT — Multiple artifact types with granular control
notebooklm generate audio "make it engaging" --wait           # Block until complete
notebooklm generate video --style whiteboard --wait           # Visual style selection
notebooklm generate cinematic-video "documentary-style summary" --wait  # Dedicated alias
notebooklm generate quiz --difficulty hard                     # Assessment creation
notebooklm generate flashcards --quantity more                 # Study material density
notebooklm generate slide-deck                                 # Presentation output
notebooklm generate infographic --orientation portrait         # Visual summary
notebooklm generate mind-map                                   # Hierarchical concept map
notebooklm generate data-table "compare key concepts"          # Structured comparison

# 7. DOWNLOAD ARTIFACTS — Local persistence in multiple formats
notebooklm download audio ./podcast.mp3
notebooklm download video ./overview.mp4
notebooklm download cinematic-video ./documentary.mp4
notebooklm download quiz --format markdown ./quiz.md           # Web UI can't export quizzes!
notebooklm download flashcards --format json ./cards.json      # Anki-import ready
notebooklm download slide-deck ./slides.pdf
notebooklm download infographic ./infographic.png
notebooklm download mind-map ./mindmap.json                    # JSON for custom viz
notebooklm download data-table ./data.csv                      # Spreadsheet analysis

Key insight: The --wait flag is critical for scripting. Without it, commands return immediately while generation happens asynchronously. For CI/CD pipelines, omit --wait and poll notebooklm metadata --json for completion status.

Example 2: Python Async API (From README)

The Python API uses modern asyncio patterns for concurrent operations:

import asyncio
from notebooklm import NotebookLMClient

async def main():
    # Initialize client from stored authentication state
    # This reads ~/.notebooklm/storage_state.json by default
    # For headless servers, pre-populate this file from a logged-in session
    async with await NotebookLMClient.from_storage() as client:
        
        # CREATE NOTEBOOK — Returns notebook object with .id, .title, .created_at
        nb = await client.notebooks.create("Research")
        
        # ADD URL SOURCE — wait=True blocks until indexing completes
        # Critical for subsequent operations that depend on source content
        await client.sources.add_url(nb.id, "https://example.com", wait=True)
        
        # CHAT — Returns structured result with .answer and .citations
        result = await client.chat.ask(nb.id, "Summarize this")
        print(result.answer)
        # Access source citations for attribution: result.citations
        
        # GENERATE AUDIO OVERVIEW — Returns status object with task tracking
        status = await client.artifacts.generate_audio(
            nb.id, 
            instructions="make it fun"  # Natural language style direction
        )
        # BLOCK UNTIL COMPLETE — Essential for sequential downloads
        await client.artifacts.wait_for_completion(nb.id, status.task_id)
        # PERSIST TO FILE — MP3 format with specified path
        await client.artifacts.download_audio(nb.id, "podcast.mp3")
        
        # GENERATE QUIZ — Structured assessment export
        status = await client.artifacts.generate_quiz(nb.id)
        await client.artifacts.wait_for_completion(nb.id, status.task_id)
        # EXPORT AS JSON — Machine-readable for LMS integration
        await client.artifacts.download_quiz(
            nb.id, 
            "quiz.json", 
            output_format="json"  # Options: json, markdown, html
        )
        
        # GENERATE MIND MAP — Hierarchical data extraction
        result = await client.artifacts.generate_mind_map(nb.id)
        # JSON export for D3.js, Cytoscape, or custom visualization tools
        await client.artifacts.download_mind_map(nb.id, "mindmap.json")

# Run the async event loop
asyncio.run(main())

Critical pattern: The async with context manager ensures proper session cleanup. The from_storage() classmethod handles authentication state persistence—no manual cookie management required. For production deployments, generate storage_state.json on a workstation with browser access, then deploy to headless servers.

Example 3: Utility Commands for Automation

These commands solve real operational problems:

# AUTHENTICATION HEALTH CHECK — Diagnose cookie expiration, account routing issues
notebooklm auth check --test

# SILENT COOKIE REFRESH — Perfect for cron jobs, systemd timers, launchd plists
# Returns 0 on success, non-zero on failure for proper error handling
notebooklm auth refresh --quiet

# BROWSER COOKIE RE-EXTRACTION — Repair broken sessions without full re-auth
notebooklm auth refresh --browser-cookies chrome

# PROFILE INSPECTION — Preview multi-account state before switching
notebooklm auth inspect --browser 'chrome::Profile 1'

# METADATA EXPORT — Full notebook state as JSON for external indexing
notebooklm metadata --json

# SHARING AUDIT — Programmatic permission inspection
notebooklm share status

# RESEARCH AGENT — Auto-import web research results
notebooklm source add-research "AI regulation 2024"

# PROFILE MANAGEMENT — Switch between Google accounts
notebooklm profile list
notebooklm profile switch work  # Seamless context change

Automation insight: Combine auth refresh --quiet with a weekly cron job to prevent session expiration. Pair metadata --json with jq for shell-based notebook inventory management.

Advanced Usage & Best Practices

After weeks of production use, these patterns separate smooth operations from frustrating debugging sessions:

Profile Isolation for Multi-Account Safety:

Always use --profile when working across personal and work Google accounts. The default profile switches can cause accidental data leakage into wrong notebooks. Explicit profile selection is your safety rail:

notebooklm create "Sensitive Work Project" --profile work
notebooklm use <id> --profile work

Prompt File Pattern for Complex Instructions:

Shell command length limits break complex generation prompts. The --prompt-file pattern (distinct from source add ./file.pdf) reads from text files:

# Write detailed instructions to file
cat > podcast_prompt.txt << 'EOF'
Create a deep-dive podcast exploring the tension between
interpretability and performance in large language models.
Use a Socratic dialogue format with two hosts.
Include specific citations from the provided sources.
EOF

# Reference in generation command
notebooklm generate audio --prompt-file ./podcast_prompt.txt --wait

Headless CI/CD Deployment:

For GitHub Actions or similar environments, pre-authenticate locally, then commit storage_state.json as an encrypted secret:

# .github/workflows/research.yml snippet
- name: Restore NotebookLM session
  run: echo "$NOTEBOOKLM_STATE" | base64 -d > ~/.notebooklm/storage_state.json
  env:
    NOTEBOOKLM_STATE: ${{ secrets.NOTEBOOKLM_STORAGE_STATE }}
- name: Generate weekly research summary
  run: notebooklm generate report --prompt-file ./weekly_brief.txt --wait

Rate Limit Defense:

Google's internal APIs throttle aggressively. Implement exponential backoff in Python scripts, and space CLI batch operations with sleep intervals. The wait_for_completion() method already handles some retry logic, but concurrent generation requests will hit limits fast.

Comparison with Alternatives

Why notebooklm-py over other approaches?

The verdict: Raw browser automation is a time sink. The web UI is intentionally limited. notebooklm-py is the only approach that gives you complete capability with production reliability.

FAQ: What Developers Ask

Is notebooklm-py officially supported by Google?

No—this is explicitly an unofficial community project. It uses undocumented internal APIs that Google can change without notice. The maintainers are transparent about this risk. Best for prototypes, research, and personal projects where you can adapt to API changes.

Will Google ban my account for using this?

There's no evidence of account bans for API usage patterns that mirror normal web usage. However, aggressive automation (hundreds of requests per minute) may trigger rate limiting. The project includes rate limit guidance and recommends reasonable usage patterns.

How do I handle authentication on a headless server?

Authenticate on any machine with a browser using notebooklm login, then copy ~/.notebooklm/storage_state.json to your server. The Python API's NotebookLMClient.from_storage() reads this file with no browser required.

Can I use this with multiple Google accounts?

Yes—profile management is a first-class feature. Use notebooklm profile list to see accounts, notebooklm profile switch <name> to change context, and --profile flags on commands for explicit targeting.

What happens when Google changes their internal API?

The project maintains RPC development documentation and protocol capture tools. The community responds to breakages quickly—check the troubleshooting guide and GitHub issues for workarounds.

Is there a synchronous Python API?

The core API is async-first (asyncio) for performance, but you can wrap calls with asyncio.run() or asyncio.get_event_loop().run_until_complete() in synchronous contexts. The CLI provides a synchronous interface for shell scripting.

How do I contribute or report issues?

See CONTRIBUTING.md for development setup, and open GitHub issues for bug reports. The project welcomes RPC protocol captures from users who discover new endpoints.

Conclusion: Your Research Deserves Better Than Clicking

Google NotebookLM is one of the most powerful AI research tools ever built. But the web UI is a deliberately simplified gateway—not the destination. Every hour you spend manually downloading files one by one, copying quiz answers by hand, or waiting for browser tabs to load is an hour stolen from actual thinking and creation.

notebooklm-py changes the equation entirely. It transforms NotebookLM from a manual tool into a programmable research infrastructure. Batch operations that took hours now complete in scripts you write once. Hidden features like PPTX export, structured quiz JSON, and mind map data extraction unlock workflows the web UI simply cannot support. Agent integration means your AI assistants can now perform research tasks autonomously.

The installation is five minutes. The learning curve is gentle—especially if you're already comfortable with Python or shell scripting. The payoff is research velocity you didn't think was possible.

Stop fighting the interface. Start programming your research.

⭐ Star the repository, install with pip install "notebooklm-py[browser]", and join the community of developers who refuse to let their tools dictate their workflows.

Your future self—reviewing ten auto-generated research summaries while your competitors are still on page three of their Google search—will thank you.