Installation Guide

s3fs is available on the major Python package managers. It currently supports Python 3.10 through 3.14.

Depending on your workflow and environment, you can install the package via Conda, pip, or directly from the source.

If you are working within a conda environment, installing via conda-forge is highly recommended. This ensures that native dependencies and compiled libraries (if any are present in your broader dependency tree) are properly resolved.

conda install s3fs -c conda-forge

Why Conda? Data science libraries like pandas and dask (which heavily use s3fs) are often easier to manage via Conda due to complex C/C++ dependencies.

PyPI (pip)

For standard Python environments, virtual environments, or Docker containers, install s3fs via pip:

pip install s3fs

Install from Source

If you need the absolute latest features, bug fixes, or wish to contribute to the project, you can install s3fs directly from the GitHub repository source code:

# Clone the repository
git clone https://github.com/fsspec/s3fs.git
cd s3fs

# Install the package
pip install .

For developers planning to modify the code, install the package in editable mode alongside testing requirements. See Development for more details.

Dependencies

s3fs is built on top of a few critical libraries. When you install s3fs, the following core dependencies are automatically installed:

  • aiobotocore (>= 2.19.0, < 4.0.0): An asynchronous wrapper around botocore. This is the engine that actually communicates with AWS APIs.
  • fsspec (== 2026.2.0): The filesystem specification library that provides the base classes and API contracts.
  • aiohttp (!= 4.0.0a0, != 4.0.0a1): The underlying asynchronous HTTP client used by aiobotocore to make network requests.

Common Installation Pitfalls

  • botocore Version Conflicts: Because aiobotocore relies heavily on internal botocore APIs, it strongly pins the botocore and boto3 versions it is compatible with. If you already have boto3 installed in your environment, installing s3fs might downgrade or upgrade boto3 to satisfy aiobotocore's requirements. This is normal, but can break other packages that require specific boto3 versions.
  • Missing AWS Credentials: Installation does not configure your AWS access. If you install s3fs but cannot read from your buckets, ensure your credentials are set up. Refer to the Usage Guide for authentication details.

Verifying the Installation

To ensure s3fs is installed correctly, you can run a quick check in your Python REPL. The following snippet verifies that the package can be imported and queries public data anonymously:

import s3fs

# Initialize an anonymous filesystem
fs = s3fs.S3FileSystem(anon=True)

# Attempt to list a known public dataset (e.g., NOAA HRRR data)
files = fs.ls("s3://noaa-hrrr-bdp-pds/")
print(f"Found {len(files)} files/folders in public bucket.")