There is NO official Python SDK for Linear. Linear's official SDK is TypeScript only (@linear/sdk). For Python, three competing community packages exist: linear-py, linear-api, and linear-python — none are official. The recommended approach for production Python use is raw GraphQL over HTTP. Current best community package is linear-api 0.2.0.
Install & Compatibility
Where this runs
tested against v? · 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
py 3.10
6/10 runs
6/10 runs
py 3.11
8/10 runs
8/10 runs
py 3.12
8/10 runs
8/10 runs
py 3.13
8/10 runs
8/10 runs
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
LinearClient
✓ from linear_api import LinearClient
✗ from linear import LinearClient
linear-api installs as linear_api, not linear. No official Python package named linear exists.
Raw GraphQL (recommended)
✓ import urllib.request # raw GraphQL over HTTP
✗ from linear_py import Linear
For production use, raw GraphQL is more reliable than any community wrapper. linear-py has very limited feature coverage.
Raw GraphQL approach — recommended for production Python use with Linear API.
import json
import urllib.request
API_KEY = 'lin_api_YOUR_KEY'
def graphql_request(query, variables=None):
data = json.dumps({'query': query, 'variables': variables or {}}).encode()
req = urllib.request.Request(
'https://api.linear.app/graphql',
data=data,
headers={
'Authorization': API_KEY,
'Content-Type': 'application/json'
}
)
with urllib.request.urlopen(req) as resp:
result = json.loads(resp.read())
if 'errors' in result:
raise Exception(result['errors'])
return result['data']
# Get current user
me = graphql_request('{ viewer { id name email } }')
print(me)
# Get issues for a team
query = '''
query TeamIssues($teamId: String!) {
team(id: $teamId) {
issues { nodes { id identifier title state { name } } }
}
}
'''
issues = graphql_request(query, {'teamId': 'YOUR_TEAM_ID'})
Debug
Known issues
breakingThere is no official Python SDK for Linear. linear-py, linear-api, and linear-python are all community packages with no official support. Linear's official SDK is TypeScript only.fixUse raw GraphQL over HTTP for production. Use linear-api for prototyping if you want an ORM-style wrapper.
affects: all
breakingGraphQL queries return 200 OK even on errors. The 'errors' array in the response must be checked explicitly — HTTP status alone does not indicate success.fixAlways check 'if errors in result' before accessing result['data'].
affects: all
breakingOAuth apps: starting October 1 2025 all newly created OAuth apps issue refresh tokens by default. Existing apps must migrate to refresh tokens by April 1 2026 or OAuth tokens will stop working.fixImplement refresh token flow before April 1 2026. See Linear OAuth developer documentation.
affects: all OAuth integrations
breakinguserPromoteAdmin, userDemoteAdmin, userPromoteMember, userDemoteMember mutations removed from GraphQL schema. Any code using these will get schema validation errors.fixUse the current user role management mutations in the schema.
affects: all
gotchaLinear API token format is 'lin_api_...' — do not use Bearer prefix. Correct header is Authorization: lin_api_... not Authorization: Bearer lin_api_...fixheaders = {'Authorization': 'lin_api_YOUR_KEY'} — no Bearer prefix. affects: all
gotchaIssue search by identifier (e.g. ENG-123) requires filtering by number first then matching identifier. Direct filter on identifier string is not supported.fixFilter by number: {'number': {'eq': 123}} then match exact identifier in results. affects: all
gotchaissueAddLabel mutation does not exist. Common LLM-generated code attempts to call it and gets a 400 error.fixUse issueUpdate with labelIds array instead.
affects: all
deprecatedlinear-python (PyPI) is an older abandoned wrapper. Do not confuse with linear-api or linear-py.fixUse linear-api for community wrapper or raw GraphQL.
affects: all
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'linear_python'
The 'linear-python' package is not installed in the current Python environment.
fixInstall the package using pip: `pip install linear-python`.
linear_python.exceptions.LinearAPIError: 401 Unauthorized
The Linear API key or authentication token provided to the 'linear-python' client is invalid, missing, or lacks the necessary permissions.
fixEnsure your Linear API key is correctly configured as an environment variable (e.g., `LINEAR_API_KEY`) or passed directly to the `LinearClient` constructor, and verify its validity and scopes in your Linear settings.
AttributeError: 'LinearClient' object has no attribute 'create_issue'
The method or attribute being called (e.g., `create_issue`) does not exist on the `LinearClient` object, or its name is different, indicating an incorrect usage of the 'linear-python' library.
fixConsult the 'linear-python' library's source code or any available documentation to find the correct method names and usage patterns, or consider using a more actively maintained library like `linear-api`.
linear_python.exceptions.LinearAPIError: 400 Bad Request: GraphQL validation error: Field 'title' is required.
The request made through 'linear-python' to the Linear API is missing a required field or contains data that does not conform to the Linear GraphQL schema.
fixExamine the specific error message to identify the missing or invalid field, and adjust your 'linear-python' call to provide the correct data according to the Linear API's GraphQL schema.
Audit
Dependencies
pydantic>=2.0requiredRequired by linear-api for model validation.
requestsoptionalHTTP client for raw GraphQL approach.