pyseq logo

PySeq

PySeq is a Python library for detecting, parsing, and formatting numbered file sequences such as fileA.0001.png, fileA.0002.png, and fileA.0003.png. It groups matching filenames into a compact sequence form like fileA.1-3.png, regardless of where the frame number appears in the name.

Used in visual effects, animation, and post-production pipelines.

Installation

The easiest way to install pyseq:

$ pip install -U pyseq

OS packages are also available for some distributions:

Ubuntu 26.04 LTS (resolute) from universe:

sudo apt install python3-pyseq

Debian unstable (sid) as python3-pyseq:

sudo apt install python3-pyseq

For environment configuration and source distribution setup, see Setup and Distribution.

Quick Examples

Find grouped sequences from Python:

>>> import pyseq
>>> seqs = pyseq.get_sequences("tests/files/*.png")
>>> print(seqs[0].format("%04l %h%p%t %R"))
0010 012_vb_110_v001.%04d.png [1-10]

Compress a list of filenames into a sequence:

>>> s = Sequence(['file.0001.jpg', 'file.0002.jpg', 'file.0003.jpg'])
>>> print(s)
file.1-3.jpg
>>> s.append('file.0006.jpg')
>>> print(s.format("%h%p%t %R"))
file.%04d.jpg [1-3, 6]

Find grouped sequences from the command line:

$ lss tests/files/z1*
   4 z1_001_v1.%d.png [1-4]
   4 z1_002_v1.%d.png [1-4]
   4 z1_002_v2.%d.png [9-12]

Deserialize a compressed sequence string:

>>> s = uncompress('./tests/012_vb_110_v001.%04d.png 1-1001', fmt='%h%p%t %r')
>>> len(s)
1001
>>> print(s.format('%04l %h%p%t %R'))
1001 012_vb_110_v001.%04d.png [1-1001]

Extended serialized range syntax is also supported for uncompression and sequence reference parsing:

>>> s = uncompress('render.%04d.exr 1001-1010x3', fmt='%h%p%t %x')
>>> print(s.frames())
[1001, 1004, 1007, 1010]
>>> print(s.format('%h%p%t %x'))
render.%04d.exr 1001-1010x3

Supported serialized range forms include:

1001-1100
1001-1100x2
1001-1100x10, 1200, 1300-1320x5
10-1x3
-10--1x3 with PYSEQ_ALLOW_NEGATIVE_FRAMES=1

Negative frame ranges are opt-in so the default filename discovery path stays fast and unopinionated. Enable them with:

export PYSEQ_ALLOW_NEGATIVE_FRAMES=1

Production Usage

pyseq has been used for many years in production visual effects and animation pipelines for parsing and manipulating image sequences. If your studio uses pyseq, we'd love to hear from you.

Command-Line Tools

PySeq comes with the following sequence-aware command-line tools:

Command	Description	Example Usage
`lss`	List image sequences in a directory	`lss shots/`
`stree`	Display sequence-aware directory tree	`stree shots/`
`sfind`	Recursively find image sequences	`sfind assets/ -name "*.exr"`
`sdiff`	Compare two sequences	`sdiff A.%04d.exr B.%04d.exr`
`sstat`	Print detailed stats about a sequence	`sstat render.%04d.exr`
`scopy`	Copy a sequence to another directory	`scopy a.%04d.exr /tmp/output/`
`srm`	Remove a sequence or frame range	`srm a.1001-1100.exr`
`smv`	Move or rename a sequence	`smv b.%04d.exr /tmp/archive/`

Docs

Additional documentation is available in the docs folder:

Contributing

Contributor guidance lives in CONTRIBUTING.md.

Testing

To run the unit tests, simply run pytest in a shell:

$ pytest tests -q

Metadata

Release files for pyseq 0.9.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pyseq 0.9.3
File	Size	Uploaded
pyseq-0.9.3.tar.gz	44.1 kB	Jul 25, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for pyseq 0.9.3
File	Interpreter	ABI	Platform	Reset
pyseq-0.9.3-py3-none-any.whl 42.3 kB Jul 25, 2026	Python 3	none	any	Details

Total release size: 86.4 kB

Release files / pyseq-0.9.3.tar.gz

Download URL	pyseq-0.9.3.tar.gz
Size	44.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`802f81b35bfce0d5bc43d95443a789a5d674fd3f8de4f06c9ef57284bfaec86b`
BLAKE2b-256 checksum How to use checksums	`b35051ab847fcaf049a9bf6c0a8483b0f02c20ca477bd6a21c269e626b2c5955`
Upload date	Jul 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.8.10`

Release files / pyseq-0.9.3-py3-none-any.whl

Download URL	pyseq-0.9.3-py3-none-any.whl
Size	42.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`6fbe21b976cff583fc90607dcdd9b03812d2387d950824389f96dd545b7dfbf9`
BLAKE2b-256 checksum How to use checksums	`fde39809c0cf24942c817c36af9abb9fb02956e17508fc36713d0bfc43848a4c`
Upload date	Jul 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.8.10`