# 파일 시스템 API[[filesystem-api]]

[HfFileSystem](/docs/huggingface_hub/v1.12.1/ko/package_reference/hf_file_system#huggingface_hub.HfFileSystem) 클래스는 [`fsspec`](https://filesystem-spec.readthedocs.io/en/latest/)을 기반으로 Hugging Face Hub에 Python 파일 인터페이스를 제공합니다.

## [HfFileSystem](Hf파일시스템)[[huggingface_hub.HfFileSystem]]

[HfFileSystem](/docs/huggingface_hub/v1.12.1/ko/package_reference/hf_file_system#huggingface_hub.HfFileSystem)은 [`fsspec`](https://filesystem-spec.readthedocs.io/en/latest/)을 기반으로 하므로 제공되는 대부분의 API와 호환됩니다. 자세한 내용은 [가이드](../guides/hf_file_system) 및 fsspec의 [API 레퍼런스](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem)를 확인하세요.

#### huggingface_hub.HfFileSystem[[huggingface_hub.HfFileSystem]]

[Source](https://github.com/huggingface/huggingface_hub/blob/v1.12.1/src/huggingface_hub/hf_file_system.py#L140)

Access a remote Hugging Face Hub repository as if were a local file system.

> [!WARNING]
> [HfFileSystem](/docs/huggingface_hub/v1.12.1/ko/package_reference/hf_file_system#huggingface_hub.HfFileSystem) provides fsspec compatibility, which is useful for libraries that require it (e.g., reading
>     Hugging Face datasets directly with `pandas`). However, it introduces additional overhead due to this compatibility
>     layer. For better performance and reliability, it's recommended to use `HfApi` methods when possible.

The file system supports paths for the `hf://` protocol, which follows those URL schemes:

* Models, Datasets and Spaces repositories:

```
hf://[@]/
hf://datasets/[@]/
hf://spaces/[@]/
```

* Buckets (generic storage):

```
hf://buckets//
```

Note: when using the [HfFileSystem](/docs/huggingface_hub/v1.12.1/ko/package_reference/hf_file_system#huggingface_hub.HfFileSystem) directly, passing the `hf://` protocol prefix is optional in paths.

Usage:

```python
>>> from huggingface_hub import hffs

>>> # List files
>>> hffs.glob("my-username/my-model/*.bin")
['my-username/my-model/pytorch_model.bin']
>>> hffs.ls("datasets/my-username/my-dataset", detail=False)
['datasets/my-username/my-dataset/.gitattributes', 'datasets/my-username/my-dataset/README.md', 'datasets/my-username/my-dataset/data.json']

>>> # Read/write files
>>> with hffs.open("my-username/my-model/pytorch_model.bin") as f:
...     data = f.read()
>>> with hffs.open("my-username/my-model/pytorch_model.bin", "wb") as f:
...     f.write(data)
```

Specify a token for authentication:
```python
>>> from huggingface_hub import HfFileSystem
>>> hffs = HfFileSystem(token=token)
```

__init__huggingface_hub.HfFileSystem.__init__https://github.com/huggingface/huggingface_hub/blob/v1.12.1/src/huggingface_hub/hf_file_system.py#L210[{"name": "*args", "val": ""}, {"name": "endpoint", "val": ": str | None = None"}, {"name": "token", "val": ": bool | str | None = None"}, {"name": "block_size", "val": ": int | None = None"}, {"name": "expand_info", "val": ": bool | None = None"}, {"name": "**storage_options", "val": ""}]

**Parameters:**

endpoint (`str`, *optional*) : Endpoint of the Hub. Defaults to .

token (`bool` or `str`, *optional*) : A valid user access token (string). Defaults to the locally saved token, which is the recommended method for authentication (see https://huggingface.co/docs/huggingface_hub/quick-start#authentication). To disable authentication, pass `False`.

block_size (`int`, *optional*) : Block size for reading and writing files.

expand_info (`bool`, *optional*) : Whether to expand the information of the files.

- ****storage_options** (`dict`, *optional*) : Additional options for the filesystem. See [fsspec documentation](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.__init__).
#### resolve_path[[huggingface_hub.HfFileSystem.resolve_path]]

[Source](https://github.com/huggingface/huggingface_hub/blob/v1.12.1/src/huggingface_hub/hf_file_system.py#L276)

Resolve a Hugging Face file system path into its components.

**Parameters:**

path (`str`) : Path to resolve.

revision (`str`, *optional*) : The revision of the repo to resolve. Defaults to the revision specified in the path.

**Returns:**

``HfFileSystemResolvedPath``

Resolved path information containing `repo_type`, `repo_id`, `revision` and `path_in_repo`.
#### ls[[huggingface_hub.HfFileSystem.ls]]

[Source](https://github.com/huggingface/huggingface_hub/blob/v1.12.1/src/huggingface_hub/hf_file_system.py#L497)

List the contents of a directory.

For more details, refer to [fsspec documentation](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.ls).

> [!WARNING]
> Note: When possible, use `HfApi.list_repo_tree()` for better performance.

**Parameters:**

path (`str`) : Path to the directory.

detail (`bool`, *optional*) : If True, returns a list of dictionaries containing file information. If False, returns a list of file paths. Defaults to True.

refresh (`bool`, *optional*) : If True, bypass the cache and fetch the latest data. Defaults to False.

revision (`str`, *optional*) : The git revision to list from.

**Returns:**

``list[Union[str, dict[str, Any]]]``

List of file paths (if detail=False) or list of file information
dictionaries (if detail=True).