Install & Compatibility
Where this runs
tested against v0.1.22 · 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.920 runs
installs and imports cleanly · install 0.0s · import 0.472s · 29MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 5.0s · import 1.114s · 161MB
105MB installed
● package 105MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
CopilotClient
✓ from copilot import CopilotClient
SubprocessConfig
✓ from copilot import SubprocessConfig
ExternalServerConfig
✓ from copilot import ExternalServerConfig
PermissionHandler
✓ from copilot.session import PermissionHandler
copilot.types
✓
✗ from copilot.types import ...
The `copilot.types` module was removed in SDK version 0.2.x. Types are now imported directly from the `copilot` package or are represented by dataclasses and keyword arguments.
This quickstart demonstrates how to initialize the `CopilotClient`, create a session, send a message, and receive a response. It utilizes Python's `asyncio` for asynchronous operations and `async with` for proper resource management. The `on_permission_request` handler is essential for tool execution within a session. Replace 'gpt-4o' with an appropriate model.
import asyncio
import os
from copilot import CopilotClient, SubprocessConfig
from copilot.session import PermissionHandler
async def main():
# Ensure COPILOT_CLI_PATH or 'copilot' in PATH for the CLI to be found
# The CLI is often bundled, but its presence is crucial.
# For programmatic authentication with BYOK, you might set API keys
# os.environ['OPENAI_API_KEY'] = os.environ.get('OPENAI_API_KEY', '')
try:
# Using async with for automatic client lifecycle management
# Use SubprocessConfig for default behavior (SDK managing CLI process)
# Or ExternalServerConfig if connecting to an already running CLI server
async with CopilotClient(SubprocessConfig()) as client:
print("Copilot client started.")
# Create a session. on_permission_request is required.
# 'model' is required when using a custom provider.
async with await client.create_session(
model="gpt-4o", # Example model, check available models with client.list_models()
on_permission_request=PermissionHandler.approve_all,
) as session:
print(f"Session created: {session.session_id}")
print("Sending message...")
# send_and_wait now takes a plain string prompt (v0.2.x+)
response = await session.send_and_wait("What is 2+2?")
if response and response.data and response.data.content:
print(f"Response: {response.data.content}")
else:
print("No content in response.")
print("Session disconnected.")
except Exception as e:
print(f"An error occurred: {e}")
if __name__ == "__main__":
asyncio.run(main())
Debug
Known issues
breakingMajor API overhaul in v0.2.x. `CopilotClient` constructor arguments, `create_session`/`resume_session` parameters, and `send`/`send_and_wait` prompts have changed. Configuration objects are now dataclasses/keyword arguments instead of loosely-typed TypedDicts. The `copilot.types` module was removed.fixUpdate `CopilotClient` instantiation (e.g., use `SubprocessConfig()` or `ExternalServerConfig()`). Pass keyword arguments directly to `create_session` and `resume_session`. Pass plain string prompts to `send` and `send_and_wait`. Update imports and references from `copilot.types` to direct imports or new dataclass structures.
affects: >=0.2.0
deprecatedThe `autoRestart` option for `CopilotClient` has been removed. It was never fully implemented and now has no effect.fixRemove any references to `autoRestart` from your `CopilotClient` options.
affects: >=0.2.0
gotchaEphemeral events (e.g., `session.idle`, delta events) are no longer included in the `session.get_messages()` history after runtime update 1.0.12. They are only observable via live event listeners.fixIf your code relies on ephemeral events, subscribe to them using `session.on('event.type', handler)` instead of relying on `get_messages()` for their historical retrieval. affects: >=0.2.1-preview.1
gotchaA GitHub Copilot subscription is generally required for the SDK to function, unless you configure a Bring Your Own Key (BYOK) setup with a custom LLM provider.fixEnsure the user account has an active GitHub Copilot subscription, or configure the SDK with a custom provider and API key if using BYOK.
affects: All versions
gotchaCopilot's AI-generated code, including outputs from the SDK, can contain errors, logical flaws, or security vulnerabilities.fixAlways review, test, and validate AI-generated content and code. Do not accept suggestions blindly, and apply secure coding practices. The SDK provides mechanisms like `on_permission_request` to gate sensitive operations.
affects: All versions
gotchaThe SDK explicitly requires Python 3.11 or newer. Older Python versions are not supported and will lead to compatibility issues or errors.fixEnsure your Python environment is running version 3.11 or later. Upgrade Python if necessary.
affects: <0.1.32 (some versions required >=3.10, but >=3.11 is now standard)
Errors
Common errors & fixes
CLI not found
The GitHub Copilot CLI is either not installed, not in your system's PATH, or the Python SDK cannot properly locate or execute it, especially on Windows where shell resolution for `.cmd` or `.bat` files might fail without explicit handling.
fixInstall the GitHub Copilot CLI (e.g., `npm install -g @github/copilot`), ensure its executable path is included in your system's PATH environment variable, and restart your terminal or IDE. If the issue persists on Windows, consider explicitly setting the `cli_path` parameter when initializing `CopilotClient` in your code.
ModuleNotFoundError: No module named 'copilot.types'
This error occurs when using code or dependent packages (like `agent-framework-github-copilot`) that rely on the old `copilot.types` module, which was removed or restructured in `github-copilot-sdk` version `0.2.x` and above.
fixUpdate any code or dependent packages to be compatible with `github-copilot-sdk >= 0.2.0`, which involves adjusting import statements and API calls according to the new SDK structure.
Connection refused
The `github-copilot-sdk` is unable to establish a connection to the local Copilot CLI server or the remote GitHub Copilot API, often due to the CLI server crashing, network restrictions (firewall, proxy), or temporary server issues.
fixVerify your internet connection, check firewall and proxy settings, ensure the Copilot CLI is running, and restart your development environment. Enabling debug logging for the SDK can provide more detailed information about the connection failure.
UnauthorizedAccessException: User is not signed into GitHub and/or doesn't have Copilot chat access.
The Copilot CLI or the `github-copilot-sdk` is not properly authenticated with your GitHub account, or your GitHub account does not have an active GitHub Copilot subscription (Pro, Business, or Enterprise).
fixRun `copilot auth login` in your terminal to authenticate the GitHub Copilot CLI. Confirm that your GitHub account has an active and valid GitHub Copilot subscription.
Upgrade
Version history
1.0.1latest on PyPI · released Jun 10, 2026
Audit
Dependencies
PythonrequiredRequires Python 3.11 or later.
GitHub Copilot CLIrequiredThe SDK communicates with the Copilot CLI in server mode. For Python, the CLI is bundled automatically, but its functionality (e.g., authentication) is prerequisite.
GitHub Copilot SubscriptionoptionalA GitHub Copilot subscription is generally required to use the SDK, unless utilizing the Bring Your Own Key (BYOK) feature with custom API providers.