Install & Compatibility
Where this runs
tested against v0.38.2 · 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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.101s · 19.6MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.5s · import 0.088s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
scour
✓ from scour import scour
sanitizeOptions
✓ scour.sanitizeOptions(options)
Used to get and modify a clean options object for optimization.
scourString
✓ scour.scourString(svg_string, options=scour_options)
The primary function for optimizing an SVG string.
This quickstart demonstrates how to programmatically optimize an SVG string using Scour. It initializes options, customizes them (e.g., to remove metadata and comments), and then processes the SVG content. It's crucial to understand the available options to achieve the desired optimization level.
import os
from scour import scour
# Create a dummy SVG input string (replace with reading from a file)
input_svg_content = '<svg width="100" height="100"><circle cx="50" cy="50" r="40" stroke="black" stroke-width="3" fill="red" /><!-- A comment --><metadata><dc:title>Test SVG</dc:title></metadata></svg>'
# Get a clean scour options object
scour_options = scour.sanitizeOptions(options=None)
# Customize options (example: remove metadata and comments)
scour_options.remove_metadata = True
scour_options.remove_comments = True
scour_options.enable_viewboxing = True # A common useful option
scour_options.indent = 'none' # Remove indentation for smaller size
# Scour the SVG string
optimized_svg_content = scour.scourString(input_svg_content, options=scour_options)
# Print or save the optimized SVG
print("Original SVG (snippet):", input_svg_content[:80], "...")
print("\nOptimized SVG (snippet):", optimized_svg_content[:80], "...")
# Example of saving to a file
# with open('output_optimized.svg', 'w') as f:
# f.write(optimized_svg_content)
# print('\nOptimized SVG saved to output_optimized.svg')
scour --version
Debug
Known issues
breakingScour is designed to optimize SVG files, which involves changing their internal structure and potentially semantics. This can lead to unexpected visual changes or even broken files, especially for hand-edited SVGs or those relying on specific structural details. Always test the output and never overwrite your original files.fixAlways save optimized output to a new file and visually inspect for unintended changes before replacing originals. Use version control for SVG assets.
affects: All versions
gotchaOlder applications that embed Python (like some versions of Inkscape) might use a specific Python interpreter (e.g., Python 2.x) and thus require `scour` to be installed for that specific environment, even if you have `scour` installed for your system's default Python 3.x. The `pip install scour` command typically targets the default Python environment.fixEnsure `scour` is installed for the exact Python interpreter used by the embedding application (e.g., `python2 -m pip install scour` if the application uses Python 2, or use the application's built-in Python package manager if available). For programmatic use, ensure your environment uses Python 3.4+.
affects: <=0.37 (Python 2.x support dropped after 0.35, Python 3.3 after 0.37, current requires 2.7 or 3.4+)
deprecatedInstallation via `setup.py install` (which `pip` might implicitly use for older packages) is being deprecated in pip versions 23.1 and later for packages that lack a `pyproject.toml`. While `scour` still installs, this might lead to future warnings or require `--use-pep517` if `wheel` is not installed.fixEnsure `wheel` is installed (`pip install wheel`). While `scour` doesn't currently have a `pyproject.toml`, future `pip` versions might handle this more gracefully or the project might eventually adopt PEP 517 metadata.
affects: All versions of `scour` with `pip >= 23.1`
gotchaWhile Scour's optimizations are typically lossless, enabling certain 'aggressive cleaning' options or encountering specific SVG structures can potentially lead to information loss or subtle rendering differences. The project's goal is an 'identically rendered image', but this is not an absolute guarantee for all inputs and all options.fixCarefully review the documentation for each optimization option. Always visually inspect optimized SVG files and consider generating a diff against the original if precise fidelity is critical. Debian's `scour` package even performs an image comparison to avoid significant visual changes.
affects: All versions, especially when using aggressive optimization flags.
Errors
Common errors & fixes
scour: command not found
The `scour` command-line executable is not found in the system's PATH environment variable, or the package was not installed correctly.
fixUse `python -m scour input.svg -o output.svg` to run it as a Python module, or add pip's script directory to your system's PATH.
ModuleNotFoundError: No module named 'scour'
The `scour` Python package has not been installed in the current Python environment or is not accessible.
fixInstall the package using pip: `pip install scour`
scour: error: unrecognized arguments: output.svg
The `scour` command-line tool requires input and output file paths to be specified using the `-i` and `-o` flags, not as direct positional arguments.
fixSpecify input and output files explicitly: `scour -i input.svg -o output.svg`
AttributeError: module 'scour' has no attribute 'run'
The `scour` module does not have a top-level `run` function; programmatic usage requires importing `scour` from `scour.scour` and passing file-like objects and a `ScourOptions` object.
fix```python
from scour.scour import scour, ScourOptions
options = ScourOptions()
options.load_defaults() # Load default optimization settings
with open('input.svg', 'r') as f_in, open('output.svg', 'w') as f_out:
scour(f_in, f_out, options)
``` Upgrade
Version history
0.38.2latest on PyPI · released Nov 22, 2020
Audit
Dependencies
sixoptionalUsed for Python 2/3 compatibility, though potentially less critical for modern Python 3.4+ environments. An open issue exists to remove it.