Install & Compatibility
Where this runs
tested against v10.14.0 · 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 1.017s · 46.1MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 3.1s · import 0.905s · 47MB
45MB installed
● package 45MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
BoxClient, BoxDeveloperTokenAuth
✓ from box_sdk_gen import BoxClient, BoxDeveloperTokenAuth
✗ from boxsdk import Client, OAuth2
As of v10, the SDK uses `box_sdk_gen` exclusively. Direct imports from `boxsdk` for client and auth classes are deprecated for new codebases or migrations to v10.
This quickstart demonstrates how to authenticate with a Developer Token and list the items in your Box root folder using the v10+ SDK's `box_sdk_gen` package. Ensure you replace 'YOUR_DEVELOPER_TOKEN' with an actual token or set the `BOX_DEVELOPER_TOKEN` environment variable.
import os
from box_sdk_gen import BoxClient, BoxDeveloperTokenAuth
# Get your Developer Token from the Box Developer Console for testing.
# It's recommended to use environment variables for sensitive information.
DEVELOPER_TOKEN = os.environ.get('BOX_DEVELOPER_TOKEN', 'YOUR_DEVELOPER_TOKEN')
def get_root_folder_items(token: str):
if not token or token == 'YOUR_DEVELOPER_TOKEN':
print("Please set the 'BOX_DEVELOPER_TOKEN' environment variable or replace 'YOUR_DEVELOPER_TOKEN' in the script.")
return
try:
auth: BoxDeveloperTokenAuth = BoxDeveloperTokenAuth(token=token)
client: BoxClient = BoxClient(auth=auth)
# Get items in the root folder (folder ID '0')
print("\nItems in your Box root folder:")
for item in client.folders.get_folder_items('0').entries:
print(f"- {item.name} ({item.type.value})")
except Exception as e:
print(f"An error occurred: {e}")
if __name__ == '__main__':
get_root_folder_items(DEVELOPER_TOKEN)
Debug
Known issues
breakingVersion 10.0.0 of `boxsdk` entirely replaces the old, manually maintained `boxsdk` package with the auto-generated `box_sdk_gen`. This introduces a new interface for all methods and requires changes to import paths (e.g., `from box_sdk_gen import ...` instead of `from boxsdk import ...`) and potentially client/auth object instantiation.fixMigrate your codebase to use imports and classes from the `box_sdk_gen` package. Consult the official migration guides for detailed steps.
affects: >=10.0.0
deprecatedBox Next Generation SDKs, which were developed in parallel, are deprecated as of September 17, 2025. While existing code will continue to function, these separate artifacts will no longer receive new features, updates, or bug fixes. Their functionalities are now integrated into the consolidated Box core SDKs (v4.x.y and v10.x.y).fixUpgrade to Box core SDK v10.x.x (recommended for new applications) or v4.x.x (for existing `boxsdk` users to access generated features while gradually migrating).
affects: All versions of Box Next Generation SDKs as separate artifacts
gotchaCommon authentication issues (e.g., 'Access denied - insufficient permission', 'No "refresh_token" parameter found', 'The "box_subject_type" value is unauthorized') often stem from misconfiguration in the Box Developer Console or not meeting prerequisites for specific authentication methods (e.g., administrator approval for Client Credentials Grant).fixCarefully review the Box Developer Console application settings and ensure they align with the chosen authentication method (OAuth 2.0, JWT, Client Credentials Grant, Developer Token). Verify client IDs, secrets, public/private keys, and ensure the application has the necessary permissions and administrator approval for your enterprise.
affects: All versions
gotchaAchieving FIPS 140-2 compliance when using the SDK, especially with JWT, requires specific setup. Python's default distributions often link against OpenSSL v1.1.1 (not FIPS compliant). You must ensure Python uses a custom SSL library (like OpenSSL 3.0) and that the `cryptography` library (a JWT dependency) is also installed with a FIPS-compliant OpenSSL version.fixRefer to Box's FIPS 140-2 compliance documentation. This typically involves building a custom Python distribution with OpenSSL 3.0 and ensuring `cryptography` is installed correctly against it.
affects: All versions using FIPS-enabled environments
gotchaBox SDK uses a modified Semantic Versioning. While `PATCH` releases are generally safe, `MINOR` versions can introduce small breaking changes, primarily to function signatures. `MAJOR` versions denote significant, potentially extensive breaking changes.fixPin your project's `boxsdk` dependency to at least the major version (`boxsdk~=10.0` or `boxsdk==10.*`) to avoid unexpected breaking changes from minor version increments. Review changelogs for minor updates.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'boxsdk'
With `boxsdk` version 10.x.x and above, the core functionality has moved to an auto-generated package named `box_sdk_gen`. Direct imports from `boxsdk` are no longer valid for many components.
fixUpdate your imports to use `box_sdk_gen` for client, authentication, and manager objects. For example, instead of `from boxsdk import Client, OAuth2`, use `from box_sdk_gen import BoxClient, BoxOAuth`.
AttributeError: 'NoneType' object has no attribute 'from_settings_file'
This error often occurs when the `from_settings_file` method for JWT authentication is called on a `None` object, typically because the settings file path is incorrect or the file cannot be read, causing the JWTAuth object to not be properly initialized. It can also arise from an incorrect import path for `JWTAuth` itself in older versions.
fixEnsure the `box_config.json` file (or whatever your settings file is named) exists at the specified path and is readable. For newer `boxsdk` versions (10+), ensure `JWTAuth` is imported from `box_sdk_gen.auth` or `box_sdk_gen`, and use `BoxJWTAuth.from_config_file()` with `JWTConfig.from_json_file()` as documented in the `box_sdk_gen` library. For older versions, explicitly import `JWTAuth` from `boxsdk.auth.jwt_auth`.
boxsdk.exception.BoxAPIException: Message: Access denied - insufficient permission Status: 403 Code: access_denied_insufficient_permissions
This error indicates that the authenticated Box account or application lacks the necessary permissions to perform the requested operation on the target resource.
fixVerify that the Box application has the correct scopes enabled in the Box Developer Console for the actions you are trying to perform, and that the user or service account authenticating has the appropriate access levels (e.g., collaborator roles, ownership) for the specific files or folders.
AttributeError: 'Client' object has no attribute 'get_retention_policies'
This `AttributeError` often means you are using an older version of the `boxsdk` that does not include the method you are trying to call, or the method name has changed in newer versions.
fixUpgrade your `boxsdk` installation to the latest version using `pip install --upgrade boxsdk` to ensure you have access to the most recent API methods. If using version 10+, ensure you are correctly importing and using the `BoxClient` and its managers as per `box_sdk_gen` documentation.
Message: No "refresh_token" parameter found Status: 400 URL: https://api.box.com/oauth2/token Method: POST
This error occurs during OAuth 2.0 authentication when the application attempts to refresh an access token without providing a valid `refresh_token`, or if the provided `refresh_token` is expired or invalid.
fixEnsure that your OAuth2 setup correctly stores and retrieves the `refresh_token` after the initial authorization flow. The `store_tokens` callback in the `OAuth2` (or `BoxOAuth` for v10+) constructor should persist both `access_token` and `refresh_token`, and these should be passed back to the `OAuth2` / `BoxOAuth` instance when re-initializing.
Upgrade
Version history
10.14.0latest on PyPI · released Aug 5, 2026
Audit
Dependencies
pyjwt>=1.7.0optionalRequired for JWT authentication, and included with the `jwt` extra.
cryptographyoptionalRequired for JWT authentication; FIPS-compliant OpenSSL setup may be needed.