{"id":2845,"library":"wordcloud","title":"WordCloud","description":"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.","status":"active","version":"1.9.6","language":"python","source_language":"en","source_url":"https://github.com/amueller/word_cloud","tags":["visualization","text analysis","nlp","word cloud","data visualization"],"install":[{"cmd":"pip install wordcloud","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for numerical operations, especially image manipulation and array handling.","package":"numpy"},{"reason":"Required for image processing, including creating and manipulating mask images.","package":"pillow"},{"reason":"Commonly used for displaying the generated word cloud images.","package":"matplotlib"}],"imports":[{"note":"Importing 'wordcloud' directly instead of 'WordCloud' class is a common mistake, leading to 'module' object not callable errors.","wrong":"import wordcloud","symbol":"WordCloud","correct":"from wordcloud import WordCloud"}],"quickstart":{"code":"from wordcloud import WordCloud\nimport matplotlib.pyplot as plt\n\n# Sample text data\ntext = \"Python programming is fun. Python is great for data science. Data visualization with Python is powerful.\"\n\n# Create a WordCloud object\nwordcloud = WordCloud(width=800, height=400, background_color='white').generate(text)\n\n# Display the generated image:\nplt.figure(figsize=(10, 5))\nplt.imshow(wordcloud, interpolation='bilinear')\nplt.axis('off') # Turn off axes for a cleaner look\nplt.title('My First Word Cloud')\nplt.show()","lang":"python","description":"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."},"warnings":[{"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.","message":"Installation 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"There 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.","severity":"breaking","affected_versions":"Potentially wordcloud < 1.9.6 with matplotlib 3.9.0+"},{"fix":"Always include `plt.axis('off')` before `plt.show()` when displaying a `wordcloud` image with `matplotlib`.","message":"When 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Older 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).","severity":"deprecated","affected_versions":"wordcloud < 1.9.x with Pillow 10+"}],"env_vars":null,"search_vec":"'1.9.6':65 'activ':45 'algorithm':54 'analysi':68 'avail':59 'cloud':18,21,71 'common':14 'current':62 'data':13,72 'effici':53 'fill':58 'flexibl':55 'focus':51 'frequenc':41 'frequent':31,48 'generat':8 'indic':39 'input':26 'known':15 'librari':6,43 'maintain':46 'mask':56 'nlp':69 'python':5 'represent':10 'size':35 'space':60 'tag':20 'take':23 'text':12,24,67 'updat':49 'version':63 'visual':9,28,66,73 'word':17,32,38,70 'wordcloud':1,2","created_at":"2026-04-11T01:45:12.506350+00:00","updated_at":"2026-04-17T00:44:40.886081+00:00","problems":[{"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.","cause":"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.","error":"error: Microsoft Visual C++ 14.0 or greater is required. Get it with \"Microsoft C++ Build Tools\": https://visualstudio.microsoft.com/visual-tools/"},{"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`).","cause":"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.","error":"ValueError: Mask must be an array of shape (height, width) or (height, width, 3) or (height, width, 4)"},{"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)`.","cause":"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.","error":"TypeError: generate_from_frequencies() missing 1 required positional argument: 'frequencies'"},{"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')`).","cause":"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).","error":"OSError: cannot open resource"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.9.6","cli_name":"","cli_version":null,"type":"library","homepage":"https://amueller.github.io/word_cloud/","github":"https://github.com/amueller/word_cloud","docs":null,"changelog":null,"pypi":"https://pypi.org/project/wordcloud/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}