Repository files navigation

PyPI package:

https://pypi.python.org/pypi/pyvips

conda package:

https://anaconda.org/conda-forge/pyvips

We have formatted docs online here:

https://libvips.github.io/pyvips/

This module wraps the libvips image processing library:

https://www.libvips.org/

The libvips docs are also very useful:

https://www.libvips.org/API/current/

If you have the development headers for libvips installed and have a working Ccompiler, this module will use cffi API mode to try to build a libvipsbinary extension for your Python.

If it is unable to build a binary extension, it will use cffi ABI modeinstead and only needs the libvips shared library. This takes longer tostart up and is typically ~20% slower in execution. You can find out ifAPI mode is being used with:

importpyvipsprint(pyvips.API_mode)

This binding passes the vips test suite cleanly and with no leaks underpython3 and pypy3 on Windows, macOS and Linux.

Programs that usepyvips don't manipulate images directly, insteadthey create pipelines of image processing operations building on a sourceimage. When the end of the pipe is connected to a destination, the wholepipeline executes at once, streaming the image in parallel from source todestination a section at a time.

Becausepyvips is parallel, it's quick, and because it doesn't need tokeep entire images in memory, it's light. For example, the libvipsspeed and memory use benchmark:

https://github.com/libvips/libvips/wiki/Speed-and-memory-use

Loads a large tiff image, shrinks by 10%, sharpens, and saves again. On thistestpyvips is typically 3x faster than ImageMagick and needs 5x lessmemory.

There's a handy chapter in the docs explaining how libvips opens files,which gives some more background.

https://www.libvips.org/API/current/How-it-opens-files.html

The quickest way to start with pyvips is by installing the binary packagewith:

$ pip install"pyvips[binary]"

This installs a self-contained package with the most commonly neededlibraries. It should just work on most common platforms, including Linux,Windows and macOS, with x64 and ARM CPUs.

If your platform is unsupported or the pre-built binary isunsuitable, you can install libvips separately instead.

You need the libvips shared library on your library search path, version 8.2or later, though at least version 8.9 is required for all features to work.See:

https://www.libvips.org/install.html

Perhaps:

$ sudo apt install libvips-dev --no-install-recommends$ pip install pyvips

With python 3.11 and later, you will need to create a venv first and addpath/to/venv to your PATH. Something like:

$ python3 -m venv~/.local$ pip install pyvips

With Homebrew:

$ brew install vips python pkg-config$ pip install pyvips

On Windows, you can download a pre-compiled binary from the libvips website.

https://www.libvips.org/install.html

You'll need a 64-bit Python. The official one works well.

You can addvips-dev-x.y\bin to yourPATH, but this will add a lot ofextra DLLs to your search path and they might conflict with other programs,so it's usually safer to setPATH in your program.

To setPATH from within Python, you need something like this at thestart of your program:

importosvipsbin=r'c:\vips-dev-8.16\bin'os.environ['PATH']=vipsbin+';'+os.environ['PATH']

For Python 3.8 and later, you need:

importosvipsbin=r'c:\vips-dev-8.16\bin'add_dll_dir=getattr(os,'add_dll_directory',None)ifcallable(add_dll_dir):add_dll_dir(vipsbin)else:os.environ['PATH']=os.pathsep.join((vipsbin,os.environ['PATH']))

Now when you import pyvips, it should be able to find the DLLs.

The Conda package includes a matching libvips binary, so just enter:

$ conda install --channel conda-forge pyvips

This sample program loads a JPG image, doubles the value of every green pixel,sharpens, and then writes the image back to the filesystem again:

importpyvipsimage=pyvips.Image.new_from_file('some-image.jpg',access='sequential')image*= [1,2,1]mask=pyvips.Image.new_from_array([    [-1,-1,-1],    [-1,16,-1],    [-1,-1,-1],],scale=8)image=image.conv(mask,precision='integer')image.write_to_file('x.jpg')

Local user install:

$ pip install -e .[binary]

Run all tests:

$ tox

Run test suite:

$ pytest

Run a specific test:

$ pytest tests/test_saveload.py

Run perf tests:

$cd tests/perf$ ./run.sh

Stylecheck:

$ flake8

Generate HTML docs indoc/build/html:

$cd doc; sphinx-build -bhtml. build/html

Regenerate enums:

Make sure you have installed a libvips with all optional packages enabled,then

$cd examples; \  ./gen-enums.py~/GIT/libvips/build/libvips/Vips-8.0.gir> enums.py

Then check and move enums.py into pyvips/.

Regenerate autodocs:

Make sure you have installed a libvips with all optional packages enabled,then

$cd doc; \  python3 -c"import pyvips; pyvips.Operation.generate_sphinx_all()"> x

And copy-pastex into the obvious place indoc/vimage.rst.

Update version number:

$ vi pyvips/version.py$ vi doc/conf.py

Update pypi package:

$ python3 -m build --sdist$ twine upload --repository pyvips dist/*$ git tag -a v3.0.0 -m"as uploaded to pypi"$ git push origin v3.0.0