aggdraw

1.4.1 verified Mon Apr 27 auth: no python

High quality drawing interface for PIL/Pillow using the Anti-Grain Geometry library. Version 1.4.1, updated irregularly.

pip install aggdraw

Common errors

error ImportError: cannot import name 'Draw' from 'aggdraw' ↓

cause Incorrect import path. The class is in the top-level module.

fix

Use: from aggdraw import Draw

error ModuleNotFoundError: No module named 'aggdraw' ↓

cause aggdraw is not installed or installation failed (requires compiler for C extension).

fix

Install with pip: pip install aggdraw. Ensure you have build tools (e.g., 'python3-dev' on Linux).

error aggdraw.Draw: AttributeError: 'Draw' object has no attribute 'text' ↓

cause The 'text' method was added in a later version or requires specific parameters.

fix

Use aggdraw version >=1.2.0. For older versions, use PIL's ImageDraw.Draw.text instead.

error RuntimeError: The truth value of an array with more than one element is ambiguous. ↓

cause Confusion with numpy arrays, but aggdraw expects PIL Images.

fix

Convert numpy array to PIL Image using Image.fromarray().

Warnings

breaking aggdraw >= 1.4.0 requires Python 3.11+. Older versions (e.g., 1.3.2) support Python 3.10 and below. ↓

fix Upgrade Python to 3.11+ or pin to aggdraw==1.3.2 if on older Python.

breaking The 'Draw' object does not work directly on PIL Images; you must call 'draw.flush()' to apply changes to the underlying image. Forgetting flush results in a blank image. ↓

fix Always call draw.flush() after drawing operations.

gotcha aggdraw uses integer coordinates; passing floats may truncate silently. ↓

fix Ensure all coordinates are integers (e.g., (int(x), int(y))).

deprecated The 'Font' class is deprecated in favor of using PIL's ImageFont directly. Font handling may change in future versions. ↓

fix Use PIL.ImageFont.truetype() and pass the font object to Draw.text().

Imports

Draw
wrong
```
from aggdraw import aggdraw
```
correct
```
from aggdraw import Draw
```
The module is named 'aggdraw', but the main class is 'Draw'.
Pen
```
from aggdraw import Pen
```
Brush
```
from aggdraw import Brush
```

Quickstart

Creates a 200x200 white image, draws a red ellipse with a black outline, and displays it.

from PIL import Image
from aggdraw import Draw, Pen, Brush

img = Image.new('RGBA', (200, 200), 'white')
draw = Draw(img)
pen = Pen('black', 3)
brush = Brush('red')
draw.ellipse((50, 50, 150, 150), pen, brush)
draw.flush()
img.show()