Install & Compatibility
Where this runs
tested against v8.0.1 · 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.619s · 18.9MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 6.2s · import 1.471s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
open
✓ from smart_open import open
smart_open
✓ import smart_open
# Access the main function as smart_open.open
✗ from smart_open import smart_open
Prior to v1.8.1, the main function was imported as `smart_open.smart_open`. Since v1.8.1 (and solidified in v2.0.0), it's `smart_open.open` to align with Python's built-in `open`.
This quickstart demonstrates how to use `smart_open.open` to read from and write to an S3 bucket. It automatically handles transparent compression/decompression based on file extension and integrates with underlying SDKs like boto3 for S3 access. Make sure your environment has appropriate cloud credentials configured.
import os
from smart_open import open
# Example for S3; similar patterns apply to GCS, Azure, etc.
# Ensure AWS credentials are configured (e.g., via environment variables, AWS CLI config, or IAM role).
# For production, consider explicit credential management via transport_params.
S3_BUCKET_NAME = os.environ.get('SMART_OPEN_S3_BUCKET', 'my-smart-open-test-bucket')
S3_KEY = 'example.txt'
S3_URL = f"s3://{S3_BUCKET_NAME}/{S3_KEY}"
# Write to S3
print(f"Writing to {S3_URL}...")
with open(S3_URL, 'w') as fout:
fout.write('Hello, smart-open from S3!\n')
fout.write('This is a second line.\n')
print("Write complete.")
# Read from S3
print(f"Reading from {S3_URL}...")
with open(S3_URL, 'r') as fin:
for line in fin:
print(f"Read line: {line.strip()}")
print("Read complete.")
Debug
Known issues
breakingAs of `smart-open` v7.5.1, the minimum supported Python version is 3.10. Earlier versions (e.g., v2.0.0) supported Python 3.5+.fixUpgrade your Python environment to 3.10 or newer. If you need to use an older Python version, pin `smart-open` to a compatible version (e.g., `<7.5.1`).
affects: >=7.5.1
breakingThe primary import for the `open` function changed from `from smart_open import smart_open` (pre-v1.8.1) to `from smart_open import open` (post-v1.8.1, solidified in v2.0.0) to align with Python's built-in `open`.fixUpdate your import statements from `from smart_open import smart_open` to `from smart_open import open`.
affects: <2.0.0 to >=2.0.0
breakingThe default read mode for `smart_open.open` changed from 'rb' (read binary) to 'r' (read text) in v1.8.1 to match the behavior of Python's built-in `open`.fixIf your code implicitly relied on 'rb' as the default, explicitly pass `mode='rb'` to `smart_open.open`.
affects: <1.8.1 to >=1.8.1
gotcha`smart-open` does not install cloud or compression library dependencies by default to keep installation size small. Functionality like S3 or GCS will fail if their respective dependencies (`boto3`, `google-cloud-storage`) are not installed.fixInstall `smart-open` with the necessary extras, e.g., `pip install 'smart-open[s3,gcs]'` for S3 and GCS support.
affects: All versions
gotchaCloud storage operations (S3, GCS, Azure) require proper credential configuration. Failing to provide credentials (e.g., via environment variables, SDK defaults, or `transport_params`) will result in authentication errors.fixRefer to the documentation for your cloud provider's SDK (e.g., boto3 for AWS, google-cloud-storage for GCS) for credential setup. You can also pass client objects or credentials via the `transport_params` argument to `smart_open.open`.
affects: All versions
deprecatedVersion 7.3.0 was yanked from PyPI because its `pyproject.toml` incorrectly claimed Python 3.7 support, even though it had already been dropped in that release train.fixAvoid installing or upgrading to `smart-open==7.3.0`. Install a subsequent patch release like `7.3.1` or the latest stable version.
affects: 7.3.0
breakingIn `smart-open` v7.4.0, the `smart_open.s3.iter_bucket` function was updated to use a single shared `concurrent.futures.ThreadPoolExecutor` and a single shared thread-safe `S3.Client`.fixReview any existing code that directly used or configured `smart_open.s3.iter_bucket` for custom thread pool or client management, as its internal concurrency model has changed. If you relied on separate clients per thread/process, adjust your logic accordingly.
affects: >=7.4.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'smart_open'
The `smart-open` library has not been installed in your current Python environment.
fixpip install smart-open
ImportError: Missing optional dependency 'boto3'. Use pip or conda to install smart-open[s3].
You are attempting to open a file from Amazon S3, but the required `boto3` dependency (part of the `s3` extra) is not installed.
fixpip install smart-open[s3]
ImportError: Missing optional dependency 'google-cloud-storage'. Use pip or conda to install smart-open[gcs].
You are attempting to open a file from Google Cloud Storage, but the required `google-cloud-storage` dependency (part of the `gcs` extra) is not installed.
fixpip install smart-open[gcs]
FileNotFoundError: [Errno 2] No such file or directory: 's3://your-bucket/non-existent-file.txt'
The specified file path or URI (e.g., S3 object key, GCS blob path, local file path) does not exist in the given storage system.
fixVerify that the file path or URI is correct and the file exists at the specified location and that you have necessary permissions.
Upgrade
Version history
8.0.1latest on PyPI · released Jul 15, 2026
Audit
Dependencies
boto3optionalRequired for Amazon S3 integration. Installed with `smart-open[s3]` extra.
google-cloud-storageoptionalRequired for Google Cloud Storage integration. Installed with `smart-open[gcs]` extra.
azure-storage-bloboptionalRequired for Azure Blob Storage integration. Installed with `smart-open[azure]` extra.
paramikooptionalRequired for SSH/SFTP integration. Installed with `smart-open[ssh]` extra.
requestsoptionalRequired for HTTP/HTTPS streaming. Installed with `smart-open[http]` extra.
hdfsoptionalRequired for HDFS/WebHDFS integration. Installed with `smart-open[webhdfs]` extra.
python-zstandardoptionalRequired for Zstandard (ZST) compression. Installed with `smart-open[zst]` extra.