# notebooklm-py: an unofficial Python API for Gemini Notebook

> notebooklm-py drives Google's NotebookLM (now Gemini Notebook) through undocumented internal endpoints, exposing batch downloads and export formats the web UI does not offer. It is a beta library for prototypes, not a dependency to build a product on.

**teng-lin/notebooklm-py** — Unofficial Python API and agentic skill for Google Gemini Notebook. 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.

- Repository: https://github.com/teng-lin/notebooklm-py
- Website: https://github.com/teng-lin/notebooklm-py
- Stars: 19,557 · Forks: 2,612
- Language: Python
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/teng-lin-notebooklm-py

## What notebooklm-py solves, and who it is aimed at

NotebookLM is a grounded engine: Gemini reads the sources you give it and answers with citations. The web UI is built for one person working in a browser tab. notebooklm-py exists for the case where the work is repetitive or programmatic. The README frames the intended users directly: developers building AI agent tools, research automation pipelines, and content generation jobs. The repository ships a root SKILL.md for GitHub and npx skills add discovery, a local notebooklm skill install command for Claude Code and .agents skill directories, and repo-level Codex guidance in AGENTS.md. So the project is two things in one repository: a Python client for the service, and an agent skill wrapper around that client.

The concrete gap it fills is bulk and format. The README lists features the web UI does not offer: batch downloads, quiz and flashcard export in multiple formats, and mind map JSON extraction. If you need one podcast from one notebook, the browser is faster. If you need the same artifact from forty notebooks, or you want the quiz as structured data rather than a screen, the UI has no path and this library does.

The package name has not followed the product. Google rebranded NotebookLM to Gemini Notebook in July 2026, per the README note, and the library drives the same underlying service unchanged while keeping the notebooklm-py name. Expect that mismatch in search results and in your own dependency list.

## How the library talks to Gemini Notebook

There is no public API here. The README is explicit that the library uses undocumented Google APIs, and the pyproject.toml keywords include rpc and client, which points at the transport style: internal RPC calls rather than a documented REST surface. That single design decision explains most of the project's other properties.

Authentication is browser-derived. The .env.example points at a storage_state.json file under a config home directory, default ~/.notebooklm, and the examples directory contains refresh_browser_cookies.py, so the expected flow is to establish a session in a browser and reuse that state from Python. For CI, the same file notes an inline option: when NOTEBOOKLM_AUTH_JSON is set, authentication is read from that variable instead of a file. The optional cookies extra (rookie-cookies) and the browser extra (playwright) exist for getting and maintaining that session.

The dependency set is deliberately small: httpx, click, rich and filelock, with upper bounds on each. The pyproject.toml comment explains the policy, capping httpx on the next minor because it is pre-1.0, and bumping caps only after smoke testing. That is a maintainer who has been bitten by a transitive major release before.

Configuration is environment-driven. NOTEBOOKLM_HOME relocates all config files, and NOTEBOOKLM_DEBUG_RPC=1 turns on RPC debug logging, which is the first thing to reach for when a call returns something unexpected. The .env.example also shows NOTEBOOKLM_READ_ONLY_NOTEBOOK_ID and an optional NOTEBOOKLM_GENERATION_NOTEBOOK_ID used by the end-to-end test suite, with a generated notebook ID cached under NOTEBOOKLM_HOME for reuse across runs.

## Install and a first real call

The project is on PyPI, so installation is a pip install. The README and related searches both point at the browser variant, which pulls in Playwright so you can establish a session without hand-copying cookies. The pyproject.toml declares Python 3.10 through 3.14.

```bash
pip install notebooklm-py
pip install "notebooklm-py[browser]"
```

The first command installs the client and CLI. The second adds the browser extra for session setup. If you want the cookie helper instead, the optional extra is named cookies.

Once installed, the CLI is the shortest path to confirming that authentication works before you write any Python. The README's recipe for agent orchestration describes the create, source add and ask sequence, and the CLI reference documents the research variant of source addition.

```bash
notebooklm create
notebooklm source add-research "your topic" --mode deep
notebooklm ask "summarise the sources"
```

The first line creates a notebook, the second runs a Deep Research query and auto-imports the results, and the third asks a question against the grounded sources. If the ask returns an answer with citations, your session is working and you can move the same calls into Python. If it fails, set NOTEBOOKLM_DEBUG_RPC=1 and retry before assuming the library is broken.

For agent use, the repository also supports installing the skill locally for Claude Code and .agents skill directories, and the root SKILL.md is discoverable via npx skills add.

## The breakage risk is the design, not a bug

Undocumented endpoints are the whole premise, and the README states the consequence in its own warning block: the library is not affiliated with Google, the APIs may break, and Google can change internal endpoints at any time. Rate limits apply and heavy usage may be throttled. The README's own recommendation is to treat it as best for prototypes, research and personal projects.

That shapes what you should not build. A support tool that answers from a notebook over MCP is a reasonable internal convenience until the day the endpoint changes. A customer-facing feature with an uptime commitment is not, because you cannot file a ticket with Google about an internal RPC you were never meant to call. The failure mode is also ambiguous: a changed endpoint and a bug in your own code can look identical from the outside, which is why NOTEBOOKLM_DEBUG_RPC exists.

The packaging reflects the same caution. The classifier is Development Status :: 4 - Beta, and the version sits at 0.8.2. Filelock in the dependency list suggests the library coordinates concurrent access to local state, which matters if you run several processes against one config home.

One claim in the README deserves scepticism: the pitch that a distilled notebook can be baked into a SKILL.md that is quote, build once, reuse with zero runtime tokens or network calls, end quote. That is true of the generated file, not of the library. The distillation step still needs a live session, and the resulting skill is only as good as the sources you fed it.

## Where the web UI or a plain RAG stack is the better choice

The honest alternative is not another Python wrapper. It is either the browser, or building the retrieval yourself.

If your workload is a handful of notebooks and interactive questions, the Gemini Notebook web UI is the correct tool. It is supported, it will not break when Google ships a change, and it needs no session file. The library only wins when volume or output format forces automation.

The second alternative is a conventional retrieval stack: chunk your documents, embed them, store the vectors, and query with your own model. The README positions the library against exactly this, describing the MCP server or plain ask as a zero-infra alternative to standing up your own vector DB and embedding pipeline. The difference in approach is where the work happens. A vector database keeps your documents and your index on infrastructure you control, and you pay for embeddings and inference on every query. notebooklm-py keeps nothing locally: storage and recall live on Google's infrastructure, per the README, and the grounding and citations come from Gemini reading your sources. You trade control and predictability for zero retrieval infrastructure and no embedding bill.

That trade is the right one when the corpus is already going into NotebookLM anyway, or when you want citations without building a citation pipeline. It is the wrong one when your documents cannot leave your environment, or when you need the retrieval path to be stable for years.

## Maintenance, upgrades and the MIT licence in practice

The repository is not archived, and the last push was on 2026-09-08. Releases are frequent and small: v0.8.0 on 2026-08-03, v0.8.1 on 2026-08-14, v0.8.2 on 2026-09-02. A three-week gap between patch releases on a beta package is a reasonable sign that someone is watching the upstream service, but it is also a reminder that 0.x versioning means minor bumps can carry breaking changes.

The upgrade cost is mostly environmental rather than code-level. Because authentication depends on browser session state, a Google-side login flow change can invalidate your storage_state.json even when the library itself has not changed. Pinning a version protects you from the library, not from the service. The pyproject.toml dependency caps are there to keep a transitive httpx or rich release from breaking your install, and the maintainer's stated policy is to bump those caps only after smoke testing, so expect the caps to lag new majors.

The licence is MIT, declared both in pyproject.toml and in the LICENSE file. That is permissive and places no conditions on your own code beyond keeping the copyright notice. It says nothing about Google's terms of service, and the README's warning that this is an unofficial library using undocumented APIs is the relevant risk statement, not the licence. Whether your use of the underlying service complies with Google's terms is a question for you or your counsel, not something the MIT grant answers.

## Conclusion

Adopt notebooklm-py for prototypes, research scripts and agent workflows that tolerate breakage, and check the docs/troubleshooting.md guide before you file a bug. Do not adopt it for anything with an uptime commitment: the README states it uses undocumented Google APIs that can change without notice, and the package is classified as Beta. Before committing, verify that authentication works in your environment (the browser extra, or NOTEBOOKLM_AUTH_JSON in CI), confirm the operations you need are covered by the CLI reference, and decide how you will detect an endpoint change rather than a bug in your own code.

## FAQ

### Is there an API for NotebookLM?

Not a documented public one. notebooklm-py is an unofficial Python library that the README says uses undocumented Google APIs, which is why it carries a warning that those APIs can change without notice.

### How to install notebooklm-py?

Install it from PyPI with pip install notebooklm-py, or pip install "notebooklm-py[browser]" if you want the Playwright-based browser extra for session setup. The package requires Python 3.10 or newer.

### How to use notebooklm-py?

The README's orchestration recipe is create, then source add, then ask, and those same operations are exposed through the CLI and the Python client. The examples directory includes quickstart.py, chat.py, notes.py and research-to-podcast.py as starting points.

### What is notebooklm-py?

It is an unofficial Python API, CLI and agentic skill for Google Gemini Notebook, the product formerly called NotebookLM. The README describes it as giving programmatic access to NotebookLM features, including some capabilities the web UI does not expose.

### How to connect notebooklm-py with Claude Code?

The repository ships a root SKILL.md for GitHub and npx skills add discovery, plus local notebooklm skill install support for Claude Code and .agents skill directories. Repo-level Codex guidance lives in AGENTS.md.

### What are Python notebooks used for?

This question is about Jupyter-style notebooks, which are unrelated to notebooklm-py. That library automates Google's Gemini Notebook service and does not provide a notebook execution environment.

## Sources

- [License: MIT](https://github.com/teng-lin/notebooklm-py/blob/main/LICENSE)
- [Project website](https://github.com/teng-lin/notebooklm-py)
- [README](https://github.com/teng-lin/notebooklm-py/blob/main/README.md)
- [Releases](https://github.com/teng-lin/notebooklm-py/releases)
- [teng-lin/notebooklm-py on GitHub](https://github.com/teng-lin/notebooklm-py)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/teng-lin-notebooklm-py