What is wordclouder?

wordclouder is a no-nonsense Python tool for generating beautiful wordcloud images from any text—file,clipboard, or piped input. Forget awkward web apps: with wordclouder, you get instant, local results, every time.

Why is this cool?

I wanted to create a simple tool that made it easy to visualize arbitrary text. With wordclouder, visualizations are just a quick command away, opening up all kinds of creative uses.

  • Everything stays local.
    No privacy worries, no tracking, no uploading your writing to “free” online wordcloud generators.
  • Works with anything.
    Books, logs, emails, speeches, code, Slack threads—if it’s text, it works.
  • Powerful automation.
    Chain it with cat, grep, or fortune to turn any data into art.
  • Fast, flexible, and hackable.
    Change colors, add stopwords, automate output—all open source and under your control.

Usage

# Generate from a file
./wordclouder.py a-new-hope.txt

# Pipe in text
cat your_notes.txt | ./wordclouder.py

# From fortune, to see what fate says
fortune | ./wordclouder.py

# Save to a specific image
./wordclouder.py script.txt -o starwars-cloud.png

# Copy any text (from browser, editor, terminal, etc), then:
xclip -selection clipboard -o | ./wordclouder.py --output ~/Pictures/clipboard-cloud.png

By default, images save to ~/Pictures/wordclouds with a timestamped name. Use -o to pick your own filename or directory.

Output Example

Sample wordcloud from 'A New Hope' *A New Hope* as a wordcloud—look sir, droids!!

Installation

🔗 View wordclouder on GitHub

Clone from GitHub:

git clone https://github.com/forfaxx/wordclouder.git
cd wordclouder
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Or, just grab the single script and run with Python 3.7+ and wordcloud installed.

Optional and advanced

Create a wrapper to easily run wordclouder globally

The following steps make it easy to run complex Python tools like wordclouder, which requires a virtual environment and may live in a folder with various assets and requirements.

To make it easier to use once set up, I have included my venv-launch.sh script. Simply put this in your PATH, then create a small wrapper shell script (also in your PATH). Once set up, this technique makes it ridiculously easy to run by automatically managing the virtual environment so you don’t have to.

  1. Copy venv-launch.sh to your PATH, e.g.:
cp venv-launch.sh ~/bin/
chmod +x ~/bin/venv-launch.sh
  1. Create a wrapper script for wordclouder

This script lets you type wordclouder from anywhere on your system

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# Create ~/bin/wordclouder with these contents:
cat > ~/bin/wordclouder <<'EOF'
#!/usr/bin/env bash
# Launches wordclouder.py inside its venv, if available

SCRIPT_DIR="$HOME/tools/wordclouder"   # Adjust this if your path is different

exec ~/bin/venv-launch.sh "$SCRIPT_DIR/wordclouder.py" "$@"
EOF

chmod +x ~/bin/wordclouder
  • Pro-Tip:
    Add ~/bin to your PATH (if not already): 
    echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
  1. Run!

Now you can run:

wordclouder somefile.txt
echo "hello world" | wordclouder

Customizing Output in wordclouder.py

You can customize the following settings in the generate_wordcloud function if desired.

1. Custom Stopwords

Find:

custom_stops = set(["said", "would", "could", "one", "also"])
stopwords = STOPWORDS.union(custom_stops)

Edit custom_stops to add/remove the exact words you want ignored in your cloud.

2. Appearance: Size, Color, Style

Find:

wc = WordCloud(
    width=800,
    height=400,
    background_color="white",
    stopwords=stopwords,
    colormap="viridis"
).generate(cleaned)

Change these parameters directly:

width and height: Output image size in pixels.

background_color: Any valid CSS color (e.g., “black”, “white”, “#222233”)

colormap: Try “plasma”, “magma”, “inferno”, “cool”, “Set2”, etc.

Full list: matplotlib colormaps

3. Example: All Tweaks at Once

**Replace your generate_wordcloud() function with: ** 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

def generate_wordcloud(text, output_path):
    """Generate and save a wordcloud image from text."""
    custom_stops = set([
        "said", "would", "could", "one", "also", "really", "like", "get"
    ])
    stopwords = STOPWORDS.union(custom_stops)
    cleaned = re.sub(r"[^\w\s]", "", text)
    cleaned = re.sub(r"\d+", "", cleaned)
    wc = WordCloud(
        width=1000,
        height=600,
        background_color="black",
        stopwords=stopwords,
        colormap="magma"
    ).generate(cleaned)
    wc.to_file(output_path)
    print(f"✅ Wordcloud saved to: {output_path}")

Clip aliases to make clipboard/pasteboard easier

On my systems I set the clip and paste aliases to make it easier to access the clipboard the same way regardless of OS.

On Linux:

# Linux clipboard (assumes xclip is installed)
alias clip='xclip -selection clipboard'
alias paste='xclip -selection clipboard -o'

On macOS:

# macOS clipboard
# for consistency with linux environment
alias clip='pbcopy'
alias paste='pbpaste'

Then you can do things like: paste | wordclouder.py

Conclusion

That’s it—a dead-simple, private way to turn any text into instant, meaningful visuals. Perfect for books, logs, song lyrics, love letters, and more, all from the CLI.

Questions or feedback? PRs welcome or Email me: feedback@adminjitsu.com