FS Next

PyFilesystem2's filesystem API, maintained for modern Python.

Install · Feature coverage · Test coverage · Roadmap · Original repository

Built on PyFilesystem2 by Will McGugan and the PyFilesystem2 contributors. FS Next preserves their code, history and MIT license, and adds focused maintenance changes. This independent fork is not an official PyFilesystem release or a from-scratch reimplementation.

Work with local directories, memory, archives and FTP through the same fs API:

from fs import open_fs

with open_fs("mem://") as storage:
    storage.writetext("hello.txt", "Hello, FS Next")
    print(storage.readtext("hello.txt"))

At a glance

Release: 0.1.0, first stable FS Next release. Audit and local measurements: 2026-10-04. See the release audit for the comparison with the actual PyPI fs==2.4.16 package.

Install

Use a fresh Python 3.10+ virtual environment:

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
python -m pip install fs-next==0.1.0

Do not install fs and fs-next together. Both distributions provide the fs package and can overwrite each other's files. Existing imports stay from fs import ..., but a package declaring Requires-Dist: fs will still ask pip to install upstream fs. Downstream dependency metadata must be migrated. See the migration guide before changing existing environments.

Support and migration

Python 3.10 remains the minimum; every later CPython minor is a support target. Required CI covers 3.10–3.14 on Linux/macOS/Windows, with a separate 3.15 preview workflow. See the support policy for the difference between configured checks, verified results and future support.

The migration guide includes a locally adapted S3 plugin installed with normal dependency resolution and checked with pip check. Its integration probe uses an S3 emulator. The test review documents new FTP date/ZIP regressions, Python 3.15 doctest compatibility, remaining skips and third-party warnings. The release audit adds FTPS transfer checks and the upstream API/behavior comparison.

Feature coverage

What comes from upstream?

FS Next starts from the complete PyFilesystem2 source at 77a8562, whose package version is 2.4.16. 57/57 retained modules means source retention, not a claim of 100% behavioral compatibility. Most functionality and tests below were built by the upstream contributors and are inherited here.

What FS Next changes

Test coverage

92.77% statement coverage (4,980 / 5,368) · 86.07% branch coverage (1,236 / 1,436).

Combined coverage.py score: 91.36%.

Measured on macOS arm64, CPython 3.14.7 with coverage.py 7.16.2 against the 0.1.0 release candidate. The full tests/ suite includes loopback FTP and FTPS. Measurement covers fs/, excluding the reusable fs/test.py test helper, using the existing coverage exclusions in setup.cfg. Subprocess-only execution is not collected. This is a single-platform snapshot, not merged coverage across CI.

Reproduce coverage from a checkout:

python -m pip install -e '.[test]' coverage==7.16.2
python -m coverage erase
python -m coverage run -m pytest tests -q \
  -W error::pytest.PytestUnraisableExceptionWarning \
  -W error::pytest.PytestUnhandledThreadExceptionWarning
python -m coverage combine
python -m coverage report

Remaining gaps: 30 tests are skipped in the macOS snapshot, deprecated API warnings remain, and remote services, arbitrary plugins and production workloads need further validation. See the release audit.

Roadmap

█████████████░░ 13 / 15 tasks complete · 87%

This is the initial maintenance roadmap, with future work proposed below and no promised dates. Each checkbox counts once; tasks differ in size. The percentage tracks this checklist, independently of inherited features and test coverage.

1. Modern Python alpha — 6/6

• Preserve upstream source, history, MIT notices and fs imports.
• Remove runtime setuptools/pkg_resources and retain opener discovery.
• Fix Python 3.14 URL behavior and modernize test dependencies.
• Fix FTP cleanup stalls and failed-opener connection cleanup.
• Pass the full suite on 3 operating systems × 3 Python versions.
• Publish an alpha via Trusted Publishing and verify a fresh PyPI install.

2. Compatibility evidence — 3/5

• Exercise a real external plugin and document its dependency-name conflict.
• Publish a reproducible coverage baseline and capability matrix.
• Add Python 3.11 and 3.13 to CI and publish the support policy.
• Validate representative S3/SSH plugins and document clean dependency migration. S3 emulator and local metadata migration completed; SSH remains.
• Validate FTPS and representative external FTP servers beyond loopback tests. Loopback FTPS contract suite completed; hosted FTP remains.

3. Stable release preparation — 4/4

• Review skipped tests and uncovered branches; add regressions for identified gaps.
• Resolve remaining deprecated API use and review runtime dependencies. Review and third-party warnings.
• Adapt upstream API documentation and publish a migration guide with tested examples. Sphinx documentation builds with warnings treated as errors.
• Complete release-candidate validation, changelog and support policy before a stable release. 0.1.0 audit.

Develop and contribute

git clone https://github.com/kmsk99/fs-next.git
cd fs-next
python -m pip install -e '.[test]'
python -m pytest tests -q

Use an activated virtual environment. Contributions that close a documented gap, add a reproducible compatibility case or fix an upstream regression are welcome. See CONTRIBUTING.md and open an issue.

python -m pip install build twine
python -m build
python -m twine check dist/*

Upstream and acknowledgements

The filesystem abstractions, implementations, documentation and much of the regression suite come from PyFilesystem2. Credit belongs to Will McGugan, Martin Larralde, Giampaolo Cimino, Geoff Jukes, and the many upstream contributors. FS Next builds on that work with a narrower modern-Python maintenance focus.

• Original repository — PyFilesystem/pyfilesystem2
• Original package — fs on PyPI
• Upstream documentation
• Preserved upstream README · Contributor credits
• MIT license and original copyright notices, retained unchanged

Upstream documentation describes the original project and may contain its package name and historical support policy. Use this README for FS Next's installation, tested scope and roadmap. Neither the original maintainers' endorsement nor official succession is implied.