{"id":8990,"library":"fileseq","title":"fileseq","description":"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.","status":"active","version":"3.1.1","language":"en","source_language":"en","source_url":"https://github.com/justinfx/fileseq","tags":["vfx","animation","file parsing","frame range","file sequence","path management"],"install":[{"cmd":"pip install fileseq","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"FileSequence","correct":"from fileseq import FileSequence"},{"symbol":"FrameSet","correct":"from fileseq import FrameSet"},{"note":"For pathlib.Path integration (added in v2.2.0)","symbol":"FilePathSequence","correct":"from fileseq import FilePathSequence"}],"quickstart":{"code":"from fileseq import FileSequence, FrameSet, FilePathSequence\n\n# Create a FileSequence from a string pattern\nseq_str = \"/path/to/render/my_shot.1001-1010#.exr\"\nsequence = FileSequence(seq_str)\n\nprint(f\"Original sequence: {sequence}\")\nprint(f\"Directory: {sequence.dirname()}\")\nprint(f\"Basename: {sequence.basename()}\")\nprint(f\"Frame range: {sequence.frameRange()}\")\nprint(f\"Padding: {sequence.padding()}\")\n\n# Iterate over individual file paths\nprint(\"Individual files:\")\nfor frame_path in sequence:\n    print(f\"  {frame_path}\")\n\n# Access frames via FrameSet\nframes = FrameSet(\"1-100x5\") # Every fifth frame from 1 to 100\nprint(f\"\\nFrameSet 1-100x5: {frames}\")\nprint(f\"First frame: {frames.start()}\")\nprint(f\"Last frame: {frames.end()}\")\n\n# Using FilePathSequence for pathlib.Path objects (v2.2.0+)\npath_seq = FilePathSequence(\"/path/to/images/shot_v01.1-50@@.jpg\")\nprint(f\"\\nFilePathSequence: {path_seq}\")\nprint(f\"First path (pathlib.Path): {path_seq.frame(path_seq.start())}\")\n","lang":"python","description":"Demonstrates how to create `FileSequence` and `FrameSet` objects, access their properties, iterate through individual file paths, and utilize `FilePathSequence` for pathlib.Path integration."},"warnings":[{"fix":"Thoroughly test existing parsing logic after upgrading to v3.0.0+.","message":"Version 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.","severity":"breaking","affected_versions":"<3.0.0 to 3.0.0+"},{"fix":"Remove any explicit `antlr4-runtime` dependencies if `fileseq` v3.1.0+ is installed. Allow `fileseq` to manage its internal parser dependency.","message":"As 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.","severity":"gotcha","affected_versions":"<3.1.0 to 3.1.0+"},{"fix":"Upgrade to `fileseq` version 3.1.1 or newer to ensure correct parsing and preservation of root path separators in UNC paths.","message":"Older 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.","severity":"gotcha","affected_versions":"<3.1.1"},{"fix":"Replace `my_sequence.setExtention(ext)` with `my_sequence.setExtension(ext)`.","message":"The `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.","severity":"deprecated","affected_versions":"All versions where `setExtention` existed"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Upgrade `fileseq` to version 3.1.1 or newer to fix UNC path parsing issues.","cause":"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.","error":"FileSeqException: Cannot parse \"//server/share/path.1-10#.exr\""},{"fix":"Change your code to use `my_sequence.setExtension(ext)`.","cause":"You are attempting to use the deprecated and misspelled method `setExtention()` instead of the correct `setExtension()`.","error":"AttributeError: 'FileSequence' object has no attribute 'setExtention'"},{"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.","cause":"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.","error":"The ANTLR Tool version 4.x.y used for code generation does not match the current runtime version 4.x.z"},{"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`.","cause":"Older versions of `fileseq` might have had issues with aggressively identifying single files as sequences or inconsistencies in the `findSequencesInList` logic.","error":"fileseq.findSequencesOnDisk(\"path/to/single_file.exr\") returns an empty list or an unexpected FileSequence object for a single file."}]}