Registry / gcp / gkeepapi

gkeepapi

JSON →
library0.17.1pypypi✓ verified 86d ago

An unofficial Python client for the Google Keep API. It enables programmatic interaction with notes, lists, and reminders, supporting CRUD operations. The library is currently at version 0.17.1 and receives maintenance releases as needed to adapt to API changes or address issues.

pip install gkeepapi
INSTALL
IMPORT
SIG · GKEEPAPI
G
gkeepapi
gcppythonv0.17.1
Install
3.1s avg
Import
641ms
Disk
33MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.17.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 0.659s · 34MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 3.1s · import 0.623s · 35MB
33MB installed
● package 33MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Keep
from gkeepapi import Keep
Note
from gkeepapi.node import Note
from gkeepapi import Note
Node types like 'Note' and 'List' reside in the `gkeepapi.node` submodule, not directly under `gkeepapi`.
InvalidUsernameOrPassword
from gkeepapi.exception import InvalidUsernameOrPassword

This quickstart demonstrates how to log in to Google Keep using an app password, create a new note, sync changes, and retrieve all notes. Environment variables are used for credentials for security. Remember to replace placeholders or set actual environment variables.

import os from gkeepapi import Keep from gkeepapi.exception import InvalidUsernameOrPassword # Recommended: Use a Google App Password for programmatic access. # Generate one at: myaccount.google.com/apppasswords # Store in environment variables or directly replace placeholders. USERNAME = os.environ.get('GKEEP_USERNAME', 'your_email@example.com') APP_PASSWORD = os.environ.get('GKEEP_APP_PASSWORD', 'your_app_password') if not USERNAME or not APP_PASSWORD or APP_PASSWORD == 'your_app_password': print("Please set GKEEP_USERNAME and GKEEP_APP_PASSWORD environment variables (or replace placeholders).") print("Consider using a Google App Password for better security.") exit(1) keep = Keep() try: # Login using username and app password success = keep.login(USERNAME, APP_PASSWORD) if success: print("Login successful!") # Create a new text note note = keep.createNote('gkeepapi Quickstart Note', 'This note was created programmatically.') print(f"Created note: '{note.title}' (ID: {note.id})") # Sync changes to Google Keep keep.sync() print("Changes synced.") # Fetch and print titles of all notes print("\nAll notes in Keep:") for n in keep.all(): print(f"- {n.title}") else: print("Login failed for an unknown reason.") except InvalidUsernameOrPassword: print("Login failed: Invalid username or app password. Double-check your credentials and ensure an App Password is used.") except Exception as e: print(f"An error occurred: {e}")
Debug
Known issues
breakingMajor API changes were introduced in versions 0.10.x, affecting authentication methods and the internal structure of node objects (`gkeepapi.node.*`). Code written for versions prior to 0.10.x will likely break.
fix
Review the official GitHub README and documentation for your target version. Update `Keep.login()` calls and refactor code that directly accesses `gkeepapi.node` attributes or relies on old node type structures.
affects: <0.10.0 to >=0.10.0
gotchaDirectly using your primary Google account password for login is highly discouraged and often fails due to Google's security policies. This can result in 'InvalidUsernameOrPassword' errors or temporary account blocks.
fix
Always use a generated Google App Password for programmatic access, or implement OAuth 2.0. App Passwords can be generated at `myaccount.google.com/apppasswords`.
affects: All
gotchaAggressive or frequent API requests can lead to temporary IP bans or rate limiting by Google, resulting in HTTP 429 (Too Many Requests) errors.
fix
Implement delays between your API calls, especially for bulk operations. Consider using exponential backoff for retries to mitigate rate limiting.
affects: All
Errors
Common errors & fixes
gkeepapi.exception.InvalidUsernameOrPassword: 400 Client Error: Bad Request for url: ...
Incorrect username/app password, or Google blocking login attempts due to security flags (e.g., using a primary password instead of an app password).
fix
Verify your Google username and App Password. Ensure you are using a generated App Password and not your main account password. If the issue persists, check your Google account's security settings for suspicious activity alerts.
AttributeError: 'Note' object has no attribute 'some_old_attribute'
Attempting to access a node attribute or method that has been renamed or removed in newer `gkeepapi` versions (especially post-0.10.x refactor).
fix
Consult the current `gkeepapi` documentation or source code to understand the updated node object structure and available attributes/methods. Update your code to use the correct names and access patterns.
requests.exceptions.HTTPError: 429 Client Error: Too Many Requests for url: ...
The Google Keep API has temporarily rate-limited your IP address due to an excessive number of requests in a short period.
fix
Reduce the frequency of your API calls. Add `time.sleep()` delays between requests, particularly in loops or batch operations. For robust applications, implement an exponential backoff strategy for retries.
Upgrade
Version history
0.17.1latest on PyPI · released Jan 5, 2026
Audit
Dependencies
requestsrequiredCore HTTP client for API communication.
protobufrequiredGoogle's data interchange format used for API communication.
google-authoptionalRequired for OAuth 2.0 authentication, an alternative to app passwords.
Agent activity
50 hits · last 30 days
node
40
OpenAI (training)
1
Resources
gkeepapi — pip install gkeepapi · libregistry