Configuration directives

weserv

syntax:	weserv proxy|filter
context:	location, if in location

Enables the Weserv module for nginx requests.

The available backend modes that can be configured are:

• proxy - process images from a remote server specified within the ?url= query parameter.
• filter - process images from responses generated by other nginx handlers (e.g. static content or proxied requests).

weserv_deny_ip

syntax:	weserv_deny_ip <CIDR>
default:	—
context:	http, server, location

Denies access to the specified IP address(es). This will only block IP addresses that are specified directly, e.g.: ?url=127.0.0.1:8080/image.png. For DNS blocking, you will need to set up a recursive DNS server, like Unbound.

weserv_connect_timeout

syntax:	weserv_connect_timeout <timeout>
default:	5s
context:	http, server, location

Defines a timeout for establishing a connection with a remote server.

weserv_send_timeout

syntax:	weserv_send_timeout <timeout>
default:	5s
context:	http, server, location

Sets a timeout for transmitting a request to a remote server. The timeout is set only between two successive write operations, not for the transmission of the whole request. If the remote server does not receive anything within this time, the connection is closed.

weserv_read_timeout

syntax:	weserv_read_timeout <timeout>
default:	15s
context:	http, server, location

Defines a timeout for reading a response from a remote server. The timeout is set only between two successive read operations, not for the transmission of the whole response. If the remote server does not transmit anything within this time, the connection is closed.

weserv_user_agent

syntax:	weserv_user_agent <user_agent>
default:	Mozilla/5.0 (compatible; ImageFetcher/9.0; +http://wsrv.nl/)
context:	http, server, location, if in location

Configures the User-Agent header that will be sent to a remote server.

weserv_max_size

syntax:	weserv_max_size <size>
default:	100m
context:	http, server, location, if in location

Sets the maximum size of an image to be processed. Set to 0 to remove this limit.

weserv_max_redirects

syntax:	weserv_max_redirects <redirects>
default:	10
context:	http, server, location, if in location

Sets the maximum number of redirection-followings allowed.

weserv_canonical_header

syntax:	weserv_canonical_header on|off
default:	on
context:	http, server, location, if in location

Determines whether the rel="canonical" response header should be set to proxied images (i.e., when configured with the proxy backend mode).

weserv_savers

syntax:	weserv_savers [jpg] [png] [webp] [avif] [tiff] [gif] [json]
default:	jpg png webp avif tiff gif json
context:	http, server, location

Enables or disables image savers to be used within the &output= query parameter. This directive accepts multiple parameters.

weserv_process_timeout

syntax:	weserv_process_timeout <time>
default:	10s
context:	http, server, location

Specifies a maximum allowed time for image processing. Set to 0 to remove this limit.

weserv_max_pages

syntax:	weserv_max_pages <pages>
default:	256
context:	http, server, location, if in location

Sets the maximum number of pages to extract for multi-page input (GIF, TIFF, PDF, WebP). Set to 0 to remove this limit.

weserv_limit_input_pixels

syntax:	weserv_limit_input_pixels <pixels>
default:	71000000
context:	http, server, location, if in location

Sets the maximum number of pixels (width × height) of an input image to be processed. Assumes image dimensions contained in the input metadata can be trusted. Set to 0 to remove this limit.

weserv_limit_output_pixels

syntax:	weserv_limit_output_pixels <pixels>
default:	71000000
context:	http, server, location, if in location

Sets the maximum number of pixels (width × height) of an output image, after any upscaling. Set to 0 to remove this limit.

weserv_quality

syntax:	weserv_quality <quality>
default:	80
context:	http, server, location, if in location

Sets the default quality to use for JPEG, WebP, TIFF and AVIF images when &q= is not specified. Acceptable values are in the range from 1 to 100.

weserv_avif_quality

syntax:	weserv_avif_quality <quality>
default:	—
context:	http, server, location, if in location

Sets the default quality to use for AVIF images when &q= is not specified. Acceptable values are in the range from 1 to 100.

If the directive is not present, then the quality specified in weserv_quality is used.

weserv_jpeg_quality

syntax:	weserv_jpeg_quality <quality>
default:	—
context:	http, server, location, if in location

Sets the default quality to use for JPEG images when &q= is not specified. Acceptable values are in the range from 1 to 100.

If the directive is not present, then the quality specified in weserv_quality is used.

weserv_tiff_quality

syntax:	weserv_tiff_quality <quality>
default:	—
context:	http, server, location, if in location

Sets the default quality to use for TIFF images when &q= is not specified. Acceptable values are in the range from 1 to 100.

If the directive is not present, then the quality specified in weserv_quality is used.

weserv_webp_quality

syntax:	weserv_webp_quality <quality>
default:	—
context:	http, server, location, if in location

Sets the default quality to use for WebP images when &q= is not specified. Acceptable values are in the range from 1 to 100.

If the directive is not present, then the quality specified in weserv_quality is used.

weserv_avif_effort

syntax:	weserv_avif_effort <effort>
default:	4
context:	http, server, location, if in location

Controls the CPU effort spent on improving AVIF compression. Acceptable values are in the range from 0 (fastest/largest) to 9 (slowest/smallest).

weserv_gif_effort

syntax:	weserv_gif_effort <effort>
default:	7
context:	http, server, location, if in location

Controls the CPU effort spent on improving GIF compression. Acceptable values are in the range from 1 (fastest/largest) to 10 (slowest/smallest).

weserv_webp_effort

syntax:	weserv_webp_effort <effort>
default:	4
context:	http, server, location, if in location

Controls the CPU effort spent on improving WebP compression. Acceptable values are in the range from 0 (fastest/largest) to 6 (slowest/smallest).

weserv_zlib_level

syntax:	weserv_zlib_level <level>
default:	6
context:	http, server, location, if in location

Sets the default zlib compression to use for PNG images when &l= is not specified. Acceptable values are in the range from 0 (fastest/largest) to 9 (slowest/smallest).

weserv_fail_on_error

syntax:	weserv_fail_on_error on|off
default:	off
context:	http, server, location, if in location

Sets the processing behavior when loading invalid images. By default, the Weserv module does a "best effort" to decode images, even if the data is corrupt or invalid. Set this flag to on if you would rather to halt processing and raise an error when loading invalid images.