fsspec

date: 2026-04-06 excerpt: fsspec（Filesystem Spec）でローカル・クラウド・リモートを統一APIで操作する

fsspec

概要

ローカルファイル・クラウドストレージ・リモートサーバーなど、あらゆるファイルシステムを統一的なAPIで操作できるPythonパッケージ
URLスキームでファイルシステム種別を指定するため、S3・GCS・SFTP・ローカルファイルを同じ open() インターフェースで扱える
pandas.read_csv("s3://...") のようにS3パスを直接渡す場合、内部的にfsspecが使われている

インストール

$ pip install fsspec

$ pip install s3fs     # AWS S3 / MinIO
$ pip install gcsfs    # Google Cloud Storage
$ pip install paramiko # SFTP

基本的な使い方

URLから直接ファイルを開く

import fsspec

for url in [
    "s3://some_bucket/foobar.txt",
    "sftp://hostname/path/to/foobar.txt",
    "file:///path/to/foobar.txt",
]:
    fs, path = fsspec.url_to_fs(url)
    with fs.open(path, "rt", encoding="utf-8") as f:
        content = f.read()

ファイルシステムオブジェクトの取得

import fsspec

fs = fsspec.filesystem("s3", key="ACCESS_KEY", secret="SECRET_KEY")

fs.ls("s3://my-bucket/")
fs.mkdir("s3://my-bucket/output/")
fs.copy("s3://my-bucket/a.txt", "s3://my-bucket/b.txt")
fs.rm("s3://my-bucket/output/", recursive=True)

認証情報の設定

設定は以下の優先順位で解決される（後のものが優先）

優先度	方法	例
低	設定ファイル（`~/.config/fsspec/`）	JSONまたはINI形式
↑	環境変数 `FSSPEC_{PROTOCOL}`	`FSSPEC_S3={"key":"...", "secret":"..."}`
↑	環境変数 `FSSPEC_{PROTOCOL}_{KWARG}`	`FSSPEC_S3_KEY=alice`
高	コード内で明示的に渡すkwargs	`fsspec.open(..., key="alice")`

# S3 / MinIO
$ export FSSPEC_S3_ENDPOINT_URL=http://localhost:9000
$ export FSSPEC_S3_KEY=alice
$ export FSSPEC_S3_SECRET=wonderland

# GCS（Application Default Credentials）
$ export FSSPEC_GCS_TOKEN=cloud

# SFTP
$ export FSSPEC_SFTP_USERNAME=alice
$ export FSSPEC_SFTP_KEY_FILENAME=~/.ssh/id_ed25519

GCSは FSSPEC_GCS_TOKEN=cloud でApplication Default Credentialsを使用する
サービスアカウントキーを使う場合は token にJSONファイルパスを指定する

対応ファイルシステム

標準組み込み（追加パッケージ不要）

プロトコル	対象	書き	URLスキーム例
`file`	ローカルディスク	✅	`file:///tmp/data.csv`
`memory`	インメモリ（テスト用）	✅	`memory://foo/bar.txt`
`zip`	ZIPアーカイブ	✅	`zip://data.csv::file://archive.zip`
`tar`	TARアーカイブ	✅	`tar://data.csv::file://archive.tar.gz`
`ftp`	FTPサーバー	✅	`ftp://user:pass@host/path`
`http`/`https`	HTTPサーバー	❌	`https://example.com/data.csv`
`sftp`/`ssh`	SFTPサーバー	✅	`sftp://host/path/to/file`
`smb`	Samba / Windows共有	✅	`smb://host/share/file`
`github`	GitHub	❌	`github://owner:repo@branch/file`

サードパーティ（追加パッケージ必要）

プロトコル	対象	書き	必要パッケージ
`s3` / `s3a`	AWS S3・MinIO・Cloudflare R2	✅	`s3fs`
`gcs` / `gs`	Google Cloud Storage	✅	`gcsfs`
`abfs` / `az`	Azure Blob Storage	✅	`adlfs`
`hdfs`	Hadoop HDFS	✅	`pyarrow`
`oci`	OCI Object Storage	✅	`ocifs`
`hf`	Hugging Face Hub	✅	`huggingface_hub`

FUSEマウント

fsspec.fuse.run() でS3やGCSなどのリモートパスをローカルディレクトリとして実際にマウントできる（experimental）

$ apt install fuse
$ pip install fusepy

import fsspec
from fsspec.fuse import run

fs = fsspec.filesystem("gcs", token="cloud")
run(fs, "my-bucket/data/", "/mnt/gcs_data/", foreground=False)
# /mnt/gcs_data/ を通常のフォルダとして操作できる

コマンドラインからも使用可能

$ python3 -m fsspec.fuse memory /usr/share /tmp/mem

FUSEマウントはほぼ全バックエンドに対応しているが、APIを直接使う方が速度面では有利
データエンジニアリング用途では gcsfs を直接使うパターンが主流

Key-Valueマッピング（FSMap）

get_mapper() でファイルシステムをdictライクなオブジェクトとして扱う方法もある（Zarr等で使用）

import fsspec

mapper = fsspec.get_mapper("s3://my-bucket/my-zarr-store/")
mapper["key1"] = b"Hello World"
print(mapper["key1"])  # b"Hello World"

Streamlitの簡易データベースとしても利用できる

import fsspec
import json
import streamlit as st

# GCS上のパスをKVストアとして使う
mapper = fsspec.get_mapper("gcs://my-bucket/app-state/")

# 書き込み
mapper["user_settings"] = json.dumps({"theme": "dark"}).encode()

# 読み込み
settings = json.loads(mapper["user_settings"].decode())
st.write(settings)

DBサーバーを立てずにGCSやS3をセッション間で共有できる簡易ストアとして使える
キーはファイル名、値はバイト列として保存される

方法	用途
`fsspec.fuse.run()`	既存コードをそのまま使いたいとき（OSレベルマウント、FUSEが必要）
`get_mapper()`	Zarr・MLパイプラインなど（FUSEは不要）
`fsspec.open()`	単発のファイル読み書き

python fsspec gcs s3 cloud storage