Skip to content
Get packs

Guide · Open source

How to use word_cloud: install, run and make word clouds in Python

Updated · written with AI from the project's own documentation and checked against our catalogue data

word_cloud is a small Python library that draws word clouds, images in which words appear larger the more often they occur in a text. This guide explains how to install it, make a cloud from a text file or piped text with the command-line tool, and where to go next in the Python API. By the end you will be able to produce a PNG image of the most common words in a document.

word_cloudamueller/word_cloud · ★ 10.5k · MIT

Quick start

  1. 1Check your Python version. Make sure you have Python 3.7 or newer, since the README says the code is tested from 3.7 through 3.13.
  2. 2Install the package. Run pip install wordcloud, or use conda install -c conda-forge wordcloud if you use conda.
  3. 3Prepare a text file. Save the text you want to visualise in a plain text file, such as mytext.txt. For PDFs, extract the text first with pdftotext.
  4. 4Generate the image. Run wordcloud_cli --text mytext.txt --imagefile wordcloud.png to write a PNG image.
  5. 5Check the options. Run wordcloud_cli --help to see all available options.
  6. 6Try the Python examples. Open examples/simple.py for a short intro, then examples/masked.py for masks and more options.

What word_cloud does

word_cloud generates word clouds, where each word's size reflects how often it appears in a text. You can use it from Python code or from a command-line tool that reads a text file or piped text and writes a PNG image.

It depends on numpy, pillow, and matplotlib, and it is released under the MIT licence.

  • Python library for adding word clouds to a script or report
  • Command-line tool, wordcloud_cli, that writes a PNG image
  • Optional masks to shape a cloud into a custom image

Install word_cloud with pip or conda

The code is tested against Python 3.7 through 3.13. If you use pip, install the package with the command below. If you use conda, install it from the conda-forge channel.

If there are no wheels available for your version of Python, installing the package requires a C compiler. The README suggests reporting an issue with your Python version and operating system before installing a compiler.

  • Requires Python 3.7 or newer
  • Installs numpy, pillow and matplotlib as dependencies
pip install wordcloud conda install -c conda-forge wordcloud

Make a word cloud from a text file on the command line

The wordcloud_cli tool reads a text file with the --text option and writes an image with --imagefile. Run wordcloud_cli --help to see all available options.

If your source is a PDF, you can pipe text into the tool. pdftotext, included by default with many Linux distributions, writes text to stdout when you pass - as the output argument, and the text is then piped to wordcloud_cli.

  • --text sets the input text file
  • --imagefile sets the output PNG file
  • Pipe text in with pdftotext for PDF files
wordcloud_cli --text mytext.txt --imagefile wordcloud.png pdftotext mydocument.pdf - | wordcloud_cli --imagefile wordcloud.png

Use word_cloud from Python code

To build a cloud in a script or report, use the WordCloud class from the library. The README points to examples/simple.py as a short introduction and examples/masked.py for more options.

The README also shows examples with colours and with Arabic text, so you can see how the output looks in those cases.

  • Start with examples/simple.py in the repository
  • Look at examples/masked.py to add a mask image
  • Set font_path on a WordCloud object to use another font

Shape a cloud with a mask or change the font

The README says you can run examples/masked.py to see how a cloud can be shaped into an image. The sample output in the README uses an image of Alice in Wonderland.

The library includes DroidSansMono.ttf, a Google font under the Apache licence. The README says it is not essential, and you can use any other font by setting the font_path variable when creating a WordCloud object.

  • Masks shape the cloud to an image
  • font_path lets you choose a different font file

What people use it for

  • Adding a word cloud to a Python script or report
  • Getting a quick picture of the most common words in a document
  • Turning a text file into a PNG image from the command line
  • Converting PDF text into a word cloud by piping pdftotext into wordcloud_cli
  • Shaping a cloud into a custom image with a mask

Frequently asked questions

How do I install word_cloud?

Run pip install wordcloud if you use pip, or conda install -c conda-forge wordcloud if you use conda. The package depends on numpy, pillow and matplotlib, which are installed alongside it.

What Python version does word_cloud need?

The README says Python 3.7 or newer, and that the code is tested against Python 3.7 through 3.13.

Is word_cloud free to use?

Yes. The library is MIT licensed. The README notes that it bundles DroidSansMono.ttf, a Google font under the Apache licence, which you can replace by setting font_path.

Do I need a C compiler to install word_cloud?

Usually not, but the README says that if there are no wheels for your Python version, installing requires a C compiler. In that case, the README suggests reporting an issue describing your Python version and operating system.

Can I make a word cloud from a PDF?

Yes, with pdftotext. The README shows piping its output into wordcloud_cli using the - argument, which sends the extracted text to stdout.

Is there a web app or point-and-click version of word_cloud?

No. The README only describes Python code and command-line usage and does not mention a web app, so people who need a browser tool will need to look elsewhere.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

word_cloud suits Python developers who want to add word clouds to scripts or reports, and anyone comfortable running a command-line tool to turn a text file into a PNG. It is not a good fit for people who need a point-and-click or browser-based tool, since the README describes only code and terminal use.

Install options & downloads