fileseq

library3.2.0pypypi✓ verified 86d ago

fileseq (version 3.1.1) is a Python library designed for robust parsing and manipulation of file sequences and frame ranges commonly found in VFX and animation workflows. It supports various frame range shorthands, including standard, comma-delimited, chunked, and staggered ranges, as well as negative frames and subframes. The library maintains an active development status with regular patch and minor releases.

data devops

pip install fileseq

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · FILESEQ

fileseq

datapythonv3.2.0

Install

1.6s avg

Import

108ms

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.2.0 · 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

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.113s · 19.3MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 1.6s · import 0.103s · 20MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

FileSequence

✓ from fileseq import FileSequence

FrameSet

✓ from fileseq import FrameSet

FilePathSequence

✓ from fileseq import FilePathSequence

For pathlib.Path integration (added in v2.2.0)

Demonstrates how to create `FileSequence` and `FrameSet` objects, access their properties, iterate through individual file paths, and utilize `FilePathSequence` for pathlib.Path integration.

from fileseq import FileSequence, FrameSet, FilePathSequence # Create a FileSequence from a string pattern seq_str = "/path/to/render/my_shot.1001-1010#.exr" sequence = FileSequence(seq_str) print(f"Original sequence: {sequence}") print(f"Directory: {sequence.dirname()}") print(f"Basename: {sequence.basename()}") print(f"Frame range: {sequence.frameRange()}") print(f"Padding: {sequence.padding()}") # Iterate over individual file paths print("Individual files:") for frame_path in sequence: print(f" {frame_path}") # Access frames via FrameSet frames = FrameSet("1-100x5") # Every fifth frame from 1 to 100 print(f"\nFrameSet 1-100x5: {frames}") print(f"First frame: {frames.start()}") print(f"Last frame: {frames.end()}") # Using FilePathSequence for pathlib.Path objects (v2.2.0+) path_seq = FilePathSequence("/path/to/images/shot_v01.1-50@@.jpg") print(f"\nFilePathSequence: {path_seq}") print(f"First path (pathlib.Path): {path_seq.frame(path_seq.start())}")

Debug

Known issues

breakingVersion 3.0.0 introduced significant architectural changes, including a complete rewrite of the internal parsing engine using ANTLR4 instead of regular expressions. While much of the API remains compatible, subtle behavioral differences or changes in how highly complex or edge-case sequence patterns are parsed might occur compared to v2.x versions.

fix

Thoroughly test existing parsing logic after upgrading to v3.0.0+.

affects: <3.0.0 to 3.0.0+

gotchaAs of v3.1.0, the `antlr4-runtime` dependency was vendored internally to prevent version conflicts with other libraries in the same environment. If you previously manually managed or relied on an external `antlr4-runtime` alongside `fileseq`, this external dependency is no longer required and attempting to force specific versions might lead to unexpected behavior.

fix

Remove any explicit `antlr4-runtime` dependencies if `fileseq` v3.1.0+ is installed. Allow `fileseq` to manage its internal parser dependency.

affects: <3.1.0 to 3.1.0+

gotchaOlder versions (prior to v3.1.1) had issues with correctly handling UNC paths (e.g., `//server/share/`) where the leading root path separator could be incorrectly stripped, leading to malformed paths or `FileNotFoundError` when resolving.

fix

Upgrade to `fileseq` version 3.1.1 or newer to ensure correct parsing and preservation of root path separators in UNC paths.

affects: <3.1.1

deprecatedThe `FileSequence.setExtention()` method (with an 'e') was deprecated in favor of `FileSequence.setExtension()` (with an 's') in older versions. While the misspelled version might still function, it is not officially supported and should be updated.

fix

Replace `my_sequence.setExtention(ext)` with `my_sequence.setExtension(ext)`.

affects: All versions where `setExtention` existed

Errors

Common errors & fixes

FileSeqException: Cannot parse "//server/share/path.1-10#.exr"

In versions prior to v3.1.1, `fileseq` could incorrectly strip leading root path separators from UNC paths, causing parsing failures or incorrect path construction.

fix

Upgrade `fileseq` to version 3.1.1 or newer to fix UNC path parsing issues.

AttributeError: 'FileSequence' object has no attribute 'setExtention'

You are attempting to use the deprecated and misspelled method `setExtention()` instead of the correct `setExtension()`.

fix

Change your code to use `my_sequence.setExtension(ext)`.

The ANTLR Tool version 4.x.y used for code generation does not match the current runtime version 4.x.z

This error typically indicates a mismatch between the ANTLR grammar version used to generate `fileseq`'s parser and the `antlr4-runtime` version available in your environment. While `fileseq` v3.1.0+ vendors its runtime internally, older `fileseq` versions or conflicts with other libraries can expose this problem.

fix

For `fileseq` v3.1.0+, ensure no other Python libraries are forcing a conflicting `antlr4-runtime` dependency. For older `fileseq` versions, try to align the `antlr4-runtime` version in your environment with the one expected by `fileseq`, or preferably, upgrade `fileseq` to version 3.1.0 or newer to benefit from the vendored runtime.

fileseq.findSequencesOnDisk("path/to/single_file.exr") returns an empty list or an unexpected FileSequence object for a single file.

Older versions of `fileseq` might have had issues with aggressively identifying single files as sequences or inconsistencies in the `findSequencesInList` logic.

fix

Ensure `fileseq` is at `v1.15.3` or newer for improvements in `yield_sequences_in_list` logic. When using `findSequencesOnDisk`, if dealing with subframes, ensure you explicitly set `allow_subframes=True`.

Upgrade

Version history

3.2.0latest on PyPI · released Apr 19, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/justinfx/fileseq ↗

packagehttps://pypi.org/project/fileseq/ ↗

docshttps://fileseq.readthedocs.io/ ↗