Install & Compatibility
Where this runs
tested against v0.0.71 · 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 2.944s · 77.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 6.3s · import 2.744s · 84MB
80MB installed
● package 80MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ from atproto import Client
AsyncClient
✓ from atproto import AsyncClient
models
✓ from atproto import models
Used for accessing low-level API models (e.g., `models.AppBskyFeedPost.Record`).
client_utils
✓ from atproto import client_utils
Provides utility functions like `TextBuilder` for rich text posts.
This quickstart demonstrates how to initialize the synchronous `Client`, log in using environment variables for credentials, and send a simple text post to the AT Protocol network (e.g., Bluesky).
import os
from atproto import Client
def main():
client = Client()
try:
# Use environment variables for sensitive credentials
handle = os.environ.get('ATPROTO_USERNAME', 'your-handle.bsky.social')
password = os.environ.get('ATPROTO_PASSWORD', 'your-app-password')
profile = client.login(handle, password)
print(f"Welcome, {profile.display_name}!")
# Send a simple text post
post_text = "Hello World from the AT Protocol Python SDK! #atproto #python"
response = client.send_post(text=post_text)
print(f"Posted: {post_text}\nURI: {response.uri}")
except Exception as e:
print(f"An error occurred: {e}")
if __name__ == '__main__':
main()
Debug
Known issues
breakingPython 3.8 support was officially dropped in `atproto` v0.0.63. Users on Python 3.8 must upgrade their Python version to 3.9 or newer.fixUpgrade Python to 3.9 or later.
affects: >=0.0.63
breakingSignificant breaking changes occurred due to Pydantic v2 migration and `libipld` integration, particularly noticeable when upgrading from much older versions. These include: positional arguments for model instantiation are no longer supported (use keyword arguments); `createdAt` (camelCase) fields are now `created_at` (snake_case); the root namespace for Bluesky API calls changed from `client.bsky` to `client.app.bsky`; and fields conflicting with Pydantic reserved names have a `_` suffix (e.g., `validation` is now `validation_`).fixReview the changelog for specific version updates. Update model instantiation to use keyword arguments, convert field names to snake_case, and adjust API calls to use the correct `client.app.bsky` namespace.
affects: likely around 0.0.4x to 0.0.5x, fully in >=0.0.63
gotchaVersion 0.0.60 contained a bug that broke session refreshing. This was fixed in version 0.0.61.fixUpgrade to `atproto` v0.0.61 or higher.
affects: 0.0.60
gotchaThe SDK is marked as 'Under construction' and 'Until the 1.0.0 release compatibility between versions is not guaranteed'. This means breaking changes can occur in minor versions without extensive prior notice.fixRegularly review release notes and test your application when upgrading. Pin exact versions for production environments.
affects: <1.0.0
gotchaThe high-level `Client` provides a simplified API ('syntax sugar') but does not cover the full range of AT Protocol functionalities. For advanced or niche operations, developers may need to interact with the lower-level XRPC API via namespaces (e.g., `client.com.atproto.server`) and models (from `atproto.models`).fixConsult the official documentation for advanced usage and low-level API interactions.
affects: All versions
gotchaUpgrading `websockets` to v15 and `pydantic` in `atproto` v0.0.63 may lead to 'differences in stability' or 'new strange warnings' from `pydantic`.fixReport any unexpected stability issues or Pydantic warnings to the library maintainers for investigation.
affects: >=0.0.63
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'atproto'
The 'atproto' package is not installed or not available in the current Python environment.
fixInstall the package using 'pip install atproto'.
ImportError: cannot import name 'Client' from 'atproto'
The 'Client' class is not found in the 'atproto' module, possibly due to an incorrect import statement or a version mismatch.
fixEnsure you are using the correct import statement: 'from atproto import Client'.
TypeError: __init__() got an unexpected keyword argument 'handle'
The 'handle' argument is not recognized in the 'Client' class constructor, likely due to changes in the SDK's API.
fixRefer to the latest SDK documentation for the correct usage of the 'Client' class and its parameters.
AttributeError: module 'atproto' has no attribute 'send_post'
The 'send_post' function is not available in the 'atproto' module, possibly due to changes in the SDK's API.
fixUse the 'Client' class to send posts: 'client = Client(); client.send_post(text)'.
ValueError: Invalid DID format
The provided Decentralized Identifier (DID) does not conform to the expected format.
fixEnsure the DID is correctly formatted as per the AT Protocol specifications.
Upgrade
Version history
0.0.71latest on PyPI · released Aug 19, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.9 or higher. Support for Python 3.8 was dropped in v0.0.63.
libipldoptionalHighly recommended for significant performance improvements in CAR decoding for custom feeds and firehose, leveraging Rust for heavy lifting. Update with `pip install -U libipld`.
websocketsrequiredUpdated to v15 in v0.0.63; potential for stability differences with the new async client.
pydanticrequiredUpdated in v0.0.63; may introduce new warnings or require changes due to Pydantic v2 migration and related breaking changes.