Install & Compatibility
Where this runs
tested against v4.0.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.95 runs
installs and imports cleanly · install 0.0s · import 0.582s · 41MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.6s · import 0.534s · 41MB
39MB installed
● package 39MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
login
✓ from github3 import login
The primary function to authenticate and get a GitHub object.
github3
✓ import github3
General module import for accessing other utilities or API functions directly.
This quickstart demonstrates how to authenticate with github3.py using a Personal Access Token (PAT), which is the recommended approach to avoid rate limits and issues with Two-Factor Authentication. It then fetches and prints the authenticated user's repositories.
import os
from github3 import login
# It's highly recommended to use a Personal Access Token (PAT) for authentication,
# especially when 2FA is enabled, to avoid repeated prompts.
# Store your token in an environment variable, e.g., GITHUB_TOKEN.
TOKEN = os.environ.get('GITHUB_TOKEN', 'YOUR_GITHUB_TOKEN') # Replace with actual token or ensure env var is set
if TOKEN and TOKEN != 'YOUR_GITHUB_TOKEN':
gh = login(token=TOKEN)
if gh:
print(f"Successfully authenticated as: {gh.me().login}")
# Example: Get your repositories
print("Your repositories:")
for repo in gh.iter_repos(type='owner'):
print(f"- {repo.name}")
else:
print("Authentication failed. Check your GITHUB_TOKEN.")
else:
print("GITHUB_TOKEN environment variable not set or is placeholder. Please set it for proper authentication.")
print("You can generate a PAT at: https://github.com/settings/tokens")
github3 --version
Debug
Known issues
breakingIn version 4.0.0, the `Comparison.commits` method was renamed to `original_commits`. The `commits` method now uses GitHub's API to get the full commit list out of the compare endpoint, enabling pagination/iterator functionality. This change affects how commit lists are retrieved from `Comparison` objects.fixUpdate calls to `Comparison.commits` to `Comparison.original_commits` for the old behavior (max 250 commits), or adapt to the new paginated `Comparison.commits` method for full commit lists.
affects: 4.0.0+
breakingStarting with version 1.0.0, methods that iterate over collections (e.g., users, organizations, issues, pull requests, teams) now return distinct 'short' classes (e.g., `ShortUser`, `ShortOrganization`, `ShortIssue`, `ShortPullRequest`, `ShortTeam`) instead of the full object. This means if you expect full attributes immediately, you might need to explicitly fetch the full object or call `refresh()` on the 'short' object.fixReview code interacting with collection iterations. If full object details are required, either fetch the full object using its ID (e.g., `gh.user(short_user.login)`) or call the `.refresh()` method on the 'short' object to populate all attributes.
affects: 1.0.0+
gotchaWhen using username/password authentication with GitHub's Two-Factor Authentication (2FA) enabled, `github3.py` will prompt for a 2FA code on *every* API call, which is highly inefficient and disruptive.fixAlways use a Personal Access Token (PAT) for authentication when 2FA is enabled. PATs can be generated from your GitHub settings and provide a more secure and seamless experience. Store tokens securely, e.g., in environment variables.
affects: All versions
gotchaFor older versions of `github3.py` (e.g., 0.9.x), retrieving the authenticated user's information was done via `gh.user()`. In newer versions (1.0.0+), the correct method is `gh.me()`. Mixing documentation versions can lead to `AttributeError`s.fixEnsure you are referencing documentation for your installed version. For current versions (1.0.0+), use `gh.me()` to get the authenticated user object.
affects: Pre-1.0.0 and 1.0.0+
gotchaWhen listing repositories via the API, GitHub often refuses to return certain attributes (e.g., `source` and `parent`) to save bandwidth. These attributes will be `None` or missing.fixIf you require these omitted attributes for a specific repository object, call the `.refresh()` method on that `Repository` object. This will make an additional API call to retrieve the full details. Example: `repo.refresh()`.
affects: All versions
gotchaVersions of `github3.py` prior to 1.3.0 supported older Python versions (e.g., Python 2.x, 3.5, 3.6). Current versions (4.x) require Python 3.7 or newer. Attempting to install or run newer versions on unsupported Python interpreters will result in errors.fixEnsure your Python environment meets the `requires_python` specification for the desired `github3.py` version. For `github3.py==4.x`, use Python 3.7+. If you must use an older Python version, consider pinning `github3.py==1.3.0`.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'github3'
The 'github3.py' library is not installed in the Python environment you are currently using.
fixRun `pip install github3.py` to install the library.
github3.exceptions.AuthenticationFailed: 401 Bad credentials
The provided GitHub username and password, or personal access token, is incorrect, expired, or lacks the necessary scopes for the requested operation.
fixAuthenticate using a valid Personal Access Token with the required scopes: `import github3; gh = github3.login(token='YOUR_PERSONAL_ACCESS_TOKEN')`
github3.exceptions.NotFoundError: 404 Not Found
The specific resource (e.g., repository, file, user, Gist) you are trying to access does not exist, or the authenticated user does not have sufficient permissions to view a private resource (GitHub returns 404 for non-existent or inaccessible private resources).
fixVerify the spelling and existence of the resource. If it's a private resource, ensure your Personal Access Token has the correct scopes and that the token is valid and active.
API rate limit exceeded for user.
Your application has made too many requests to the GitHub API within a short period, exceeding the allotted rate limit (either primary or secondary).
fixImplement error handling to check the `X-RateLimit-Remaining` and `X-RateLimit-Reset` headers in API responses, and pause requests until the reset time. Using a Personal Access Token significantly increases the rate limit compared to unauthenticated requests. For example, `gh.rate_limit()` can retrieve current rate limit status.
AttributeError: 'GitHub' object has no attribute 'me'
You are attempting to access a method or attribute that has been renamed or removed in the version of `github3.py` you are using (e.g., `me()` was renamed to `user()`), or the object type does not support that attribute.
fixConsult the official `github3.py` documentation for your installed version to use the correct method or attribute. For this specific error, change `gh.me()` to `gh.user()`.
Upgrade
Version history
4.0.1latest on PyPI · released Apr 26, 2023
Audit
Dependencies
requestsrequiredHTTP client for making requests to the GitHub API.
uritemplaterequiredUsed for URI template expansion.
python-dateutilrequiredFor parsing dates and times from the API responses.
PyJWTrequiredUsed for JSON Web Token (JWT) handling, likely for app authentication.