wordcloud

library1.9.6pypypi✓ verified 24d ago

WordCloud is a Python library for generating visual representations of text data, commonly known as word clouds or tag clouds. It takes text as input and visualizes the most frequent words, with the size of each word indicating its frequency. The library is actively maintained, with frequent updates, and focuses on efficient algorithms, flexible masking, and filling available space. The current version is 1.9.6.

data

pip install wordcloud

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WORDCLOUD

wordcloud

datapythonv1.9.6

Install

7.7s avg

Import

1005ms

Disk

183MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.9.6 · 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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 1.030s · 179.4MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 7.7s · import 0.980s · 172MB

183MB installed

● package 183MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

WordCloud

✓ from wordcloud import WordCloud

✗ import wordcloud

Importing 'wordcloud' directly instead of 'WordCloud' class is a common mistake, leading to 'module' object not callable errors.

This quickstart generates a basic word cloud from a sample string and displays it using Matplotlib. It demonstrates the core `WordCloud` class instantiation, text generation, and image display.

from wordcloud import WordCloud import matplotlib.pyplot as plt # Sample text data text = "Python programming is fun. Python is great for data science. Data visualization with Python is powerful." # Create a WordCloud object wordcloud = WordCloud(width=800, height=400, background_color='white').generate(text) # Display the generated image: plt.figure(figsize=(10, 5)) plt.imshow(wordcloud, interpolation='bilinear') plt.axis('off') # Turn off axes for a cleaner look plt.title('My First Word Cloud') plt.show()

Debug

Known issues

gotchaInstallation can fail if a pre-built wheel is not available for your specific Python version and operating system. This is because `wordcloud` includes some C code that requires a C compiler to build if a wheel is not found.

fix

Ensure you have a C compiler installed (e.g., build-essential on Linux, Xcode command-line tools on macOS, Visual C++ Build Tools on Windows) or check for compatible pre-built wheels for your environment.

affects: All versions

breakingThere have been reports of incompatibility with `matplotlib` version 3.9.0. Users might encounter issues when trying to display word clouds with this specific `matplotlib` version.

fix

Check the `wordcloud` GitHub issues for updates and potential fixes. If encountering issues, try downgrading `matplotlib` to a known compatible version (e.g., 3.8.x) or upgrading `wordcloud` to its latest version (1.9.6 or newer) which might include a fix.

affects: Potentially wordcloud < 1.9.6 with matplotlib 3.9.0+

gotchaWhen displaying word clouds using `matplotlib`, omitting `plt.axis('off')` will result in axes and tick marks appearing around the image, which is usually undesirable for word cloud visualizations.

fix

Always include `plt.axis('off')` before `plt.show()` when displaying a `wordcloud` image with `matplotlib`.

affects: All versions

deprecatedOlder versions of `wordcloud` (e.g., 1.8.2.2) generated `DeprecationWarning` messages related to `Pillow`'s `textsize` function being deprecated and removed in `Pillow` 10 (July 2023).

fix

Upgrade `wordcloud` to the latest version (1.9.6 or newer) to ensure compatibility with recent `Pillow` versions. If unable to upgrade `wordcloud`, consider pinning `Pillow` to a version older than 10.

affects: wordcloud < 1.9.x with Pillow 10+

Errors

Common errors & fixes

error: Microsoft Visual C++ 14.0 or greater is required. Get it with "Microsoft C++ Build Tools": https://visualstudio.microsoft.com/visual-tools/

The wordcloud library includes C extensions that require a C++ compiler to be installed for building from source, which 'pip' attempts if a pre-compiled wheel is unavailable for your system.

fix

On Windows, install the 'Desktop development with C++' workload via Visual Studio Installer, or directly download 'Microsoft C++ Build Tools' from the provided link.

ValueError: Mask must be an array of shape (height, width) or (height, width, 3) or (height, width, 4)

The image provided as a mask is not correctly loaded or processed into a NumPy array with the expected dimensions, or transparent areas are not properly defined for masking.

fix

Load the mask image using `Pillow` and `numpy`, ensuring it's converted to a NumPy array and transparent pixels are set to 255 to act as a valid mask (e.g., `mask = np.array(Image.open('mask.png')); mask[mask.ndim-1 == 0] = 255`).

TypeError: generate_from_frequencies() missing 1 required positional argument: 'frequencies'

The `generate_from_frequencies` method requires a dictionary as input where keys are words (strings) and values are their corresponding frequencies (numbers), but an incorrect data type or structure was provided.

fix

Prepare your data as a dictionary like `{'word1': 10, 'word2': 5, 'word3': 12}` and pass this dictionary directly: `wordcloud.generate_from_frequencies(your_frequency_dict)`.

OSError: cannot open resource

The `font_path` provided to the `WordCloud` constructor is incorrect, points to a non-existent file, or the file is not a valid TrueType Font (TTF) or OpenType Font (OTF).

fix

Ensure the `font_path` points to a valid and accessible `.ttf` or `.otf` font file on your system (e.g., `WordCloud(font_path='/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf')`).

Upgrade

Version history

1.9.6latest on PyPI · released Jan 22, 2026

Audit

Dependencies

numpyrequiredRequired for numerical operations, especially image manipulation and array handling.

pillowrequiredRequired for image processing, including creating and manipulating mask images.

matplotlibrequiredCommonly used for displaying the generated word cloud images.

Agent activity

60 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/amueller/word_cloud ↗

packagehttps://pypi.org/project/wordcloud/ ↗

homepagehttps://amueller.github.io/word_cloud/ ↗