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
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.659s · 34MB
glibcpy 3.10–3.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.fixReview 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.fixAlways 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.fixImplement 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).
fixVerify 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).
fixConsult 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.
fixReduce 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.