Install & Compatibility
Where this runs
tested against v1.17.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.915 runs
installs and imports cleanly · install 0.0s · import 0.959s · 78.3MB
glibcpy 3.10–3.915 runs
installs and imports cleanly · install 3.0s · import 0.885s · 28MB
57MB installed
● package 57MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
BoxClient
✓ from box_sdk_gen import BoxClient
BoxDeveloperTokenAuth
✓ from box_sdk_gen import BoxDeveloperTokenAuth
BoxJWTAuth
✓ from box_sdk_gen.jwt_auth import BoxJWTAuth
✗ from box_sdk_gen import BoxJWTAuth
JWT authentication classes are found in the `jwt_auth` submodule.
CCGConfig
✓ from box_sdk_gen.ccg_auth import CCGConfig
✗ from box_sdk_gen import CCGConfig
Client Credentials Grant configuration is in the `ccg_auth` submodule.
This quickstart demonstrates how to authenticate using a Developer Token and fetch information about the current user and list items in the root folder. For production environments, consider more robust authentication methods like OAuth 2.0 or JWT. The developer token should be obtained from your Box Developer Console.
import os
from box_sdk_gen import BoxClient, BoxDeveloperTokenAuth
# It's recommended to set your developer token as an environment variable
# For testing, you can replace os.environ.get with your actual token string
DEVELOPER_TOKEN = os.environ.get('BOX_DEVELOPER_TOKEN', 'YOUR_DEVELOPER_TOKEN')
if not DEVELOPER_TOKEN or DEVELOPER_TOKEN == 'YOUR_DEVELOPER_TOKEN':
print("Please set the BOX_DEVELOPER_TOKEN environment variable or replace the placeholder.")
else:
try:
auth = BoxDeveloperTokenAuth(token=DEVELOPER_TOKEN)
client = BoxClient(auth=auth)
# Get information about the current user
me = client.users.get_user_me()
print(f"Hello, I'm {me.name} (ID: {me.id}) - Login: {me.login}")
# List items in the root folder (ID '0')
print("\nItems in your root folder:")
root_folder_items = client.folders.get_folder_items('0').entries
if root_folder_items:
for item in root_folder_items:
print(f" - {item.type.value.capitalize()}: {item.name} (ID: {item.id})")
else:
print(" No items found in the root folder.")
except Exception as e:
print(f"An error occurred: {e}")
print("Please ensure your developer token is valid and has the necessary permissions.")
Debug
Known issues
breakingThe standalone `box-sdk-gen` package is deprecated as of September 17, 2025. It will no longer receive new features, updates, bug fixes, or security patches. All future development is consolidated into the `boxsdk` package (version 10.0.0 and higher).fixMigrate your project to use `boxsdk` version 10.0.0 or higher. Install with `pip install boxsdk>=10`. The `box_sdk_gen` module will be available within the `boxsdk` package, so imports like `from box_sdk_gen import ...` will continue to work after migration.
affects: < 1.17.0 (as standalone)
gotchaWhen upgrading to `boxsdk` v10+, significant interface changes may be present, especially for older `boxsdk` users. While `box_sdk_gen` retains its internal structure, the overarching `boxsdk` client instantiation and some method signatures may have been updated.fixConsult the Box SDK versioning strategy and migration guides for detailed instructions when moving to the consolidated `boxsdk` package. Thoroughly test your application after upgrading.
affects: All versions when migrating from older `boxsdk` to `boxsdk>=10`
gotchaUsing a Developer Token is suitable only for testing and development. These tokens are short-lived and cannot be refreshed, making them unsuitable for production applications.fixFor production, implement more secure and robust authentication methods such as OAuth 2.0, Client Credentials Grant (CCG), or JSON Web Token (JWT) as detailed in the official Box authentication documentation.
affects: All versions
gotchaSpecific authentication classes (e.g., for JWT, CCG) are located in submodules like `box_sdk_gen.jwt_auth` or `box_sdk_gen.ccg_auth`, not directly under `box_sdk_gen`.fixEnsure correct import paths for authentication-related classes, e.g., `from box_sdk_gen.jwt_auth import BoxJWTAuth` or `from box_sdk_gen.ccg_auth import CCGConfig`.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'box_sdk_gen'
The standalone `box-sdk-gen` package is deprecated and no longer receives updates. Its functionalities have been consolidated into the `boxsdk` package (version 10.0.0 and higher), which now contains the `box_sdk_gen` module. This error occurs when the deprecated `box-sdk-gen` package is not installed, or an older `boxsdk` version (before 10.0.0) is used, and code attempts to import `box_sdk_gen` directly.
fixInstall or upgrade to `boxsdk` version 10 or higher using `pip install "boxsdk>=10"`. The `box_sdk_gen` module will then be available as part of the `boxsdk` installation, allowing imports like `from box_sdk_gen import BoxClient`.
ModuleNotFoundError: No module named 'boxsdk'
This error can occur when `boxsdk` version 10 or higher is installed, but the code is attempting to import modules using outdated paths from earlier `boxsdk` versions (e.g., `from boxsdk.object.folder import Folder`). In `boxsdk` version 10 and above, the primary module for accessing Box API functionalities is `box_sdk_gen`, which is included within the `boxsdk` package.
fixEnsure `boxsdk>=10` is installed. Update import statements to use the `box_sdk_gen` module for Box API interactions, for example, replace `from boxsdk import Client` with `from box_sdk_gen import BoxClient`.
ModuleNotFoundError: No module named 'box_sdk_gen.auth'
Authentication classes and their import paths have changed with the consolidation of `box-sdk-gen` into `boxsdk>=10`. Direct import from `box_sdk_gen.auth` is no longer the correct path for accessing authentication components in the latest versions.
fixImport authentication classes, such as `BoxDeveloperTokenAuth` or `BoxJWTAuth`, directly from the top-level `box_sdk_gen` package, for example: `from box_sdk_gen import BoxClient, BoxDeveloperTokenAuth`.
AttributeError: 'NoneType' object has no attribute 'fromsettings_file'
This `AttributeError` typically arises when an authentication configuration object (e.g., `JWTConfig`) is not properly instantiated or populated with required parameters before attempting to use it, leading to a `None` object being passed where an actual configuration is expected. It can also stem from using methods or properties that have changed names or structures between older `boxsdk` versions and `box_sdk_gen`.
fixEnsure all necessary authentication parameters are provided when initializing the specific configuration class (e.g., `JWTConfig`) and that the authentication object (e.g., `BoxJWTAuth`) is correctly instantiated with this configuration. Additionally, if using JWT, confirm that `pip install "boxsdk[jwt]>=10"` was executed to install the required dependencies.
Upgrade
Version history
1.17.0latest on PyPI · released Sep 5, 2025
Audit
Dependencies
PyJWToptionalRequired for JWT authentication, installed via 'boxsdk[jwt]' extra.