Skip to main content

Programming fundamentals · Beginner · 16 min

Count words in a text with a dictionary

By Padding · Updated 18 Nov 2026
Python 3.15.2 · python:3.15-slim

You will count how often each word appears in a text, first with a plain Python dictionary, then with .get() and collections.Counter, and finish with a script that prints the most common words in any text file.

On this page

A dictionary stores pairs: a key you look things up by, and a value that goes with it. A phone book is the usual picture, but a dictionary is just as good at counting. Make each word a key and the number of times you have seen it the value, and one pass through a text gives you a full word count.

Counting is one of the most common jobs in programming. Search engines count words to decide what a page is about, shops count which products sell, and analysts count answers in a survey. The same handful of lines does all of it.

In this tutorial you count the words in two short paragraphs from Charles Dickens' A Tale of Two Cities (1859, public domain). You build the count three ways, each shorter than the last, meet the two errors dictionaries throw at beginners, sort words by how often they appear, keep a separate count for each paragraph, and finish with wordcount.py, a script you can point at any text file.

Every command uses python3. If your command is python3.15 or py, type that instead. On an Android phone, the Termux app runs Python and every script here, with no downloads after Python itself.

Step 1 · Save a text and split it into words

Make a folder to work in and save the sample text as text.txt. The blank line in the middle separates the two paragraphs, which matters in a later step:

Bash
mkdir -p ~/word-count-demo
cd ~/word-count-demo
cat > text.txt <<'TXT'
It was the best of times, it was the worst of times, it was the age of
wisdom, it was the age of foolishness, it was the epoch of belief, it was
the epoch of incredulity, it was the season of Light, it was the season of
Darkness, it was the spring of hope, it was the winter of despair.

There were a king with a large jaw and a queen with a plain face, on the
throne of England; there were a king with a large jaw and a queen with a
fair face, on the throne of France.
TXT

Before you can count words, you need a clean list of them. Write a small file, words.py, with one function that every later script reuses:

Bash
cat > words.py <<'PY'
from pathlib import Path

PUNCTUATION = ".,;:!?\"'()"


def read_words(path):
    text = Path(path).read_text(encoding="utf-8")
    words = []
    for raw in text.split():
        word = raw.strip(PUNCTUATION).lower()
        if word:
            words.append(word)
    return words
PY
cat > show_words.py <<'PY'
from words import read_words

words = read_words("text.txt")
print(len(words), "words")
print(words[:8])
PY
python3 show_words.py

Line by line:

  • Path(path).read_text(encoding="utf-8") reads the whole file into one string. encoding="utf-8" makes the script read accented letters and other alphabets the same way on every computer.
  • text.split() with nothing in the brackets cuts the string wherever there is a space, tab or line break, and throws the gaps away. You get pieces such as times, with the comma still attached.
  • raw.strip(PUNCTUATION) removes any of the listed characters from both ends of a piece, so times, becomes times. The \" inside the string is a double quote, written with a backslash so it does not end the string.
  • .lower() turns It and it into the same word. Without it, Python would count them separately.
  • if word: skips anything that was only punctuation, such as a lone dash, because an empty string counts as false.
  • from words import read_words in the second script loads the function from words.py. The two files must sit in the same folder.

Check it worked

The output is 100 words, then ['it', 'was', 'the', 'best', 'of', 'times', 'it', 'was']. Every word is lower case and no commas are left.

Step 2 · Count with a dictionary, if and else

Now count. The idea: start with an empty dictionary, look at each word in turn, and either add one to its count or, the first time you meet it, set its count to 1:

Bash
cat > count_if.py <<'PY'
from words import read_words

counts = {}
for word in read_words("text.txt"):
    if word in counts:
        counts[word] = counts[word] + 1
    else:
        counts[word] = 1

print(counts["it"], counts["was"], counts["king"])
print(len(counts), "different words")
PY
python3 count_if.py
  • counts = {} makes an empty dictionary.
  • word in counts asks whether word is already a key. It checks keys, not values, and it is fast however large the dictionary grows, because a dictionary jumps straight to a key instead of reading every entry.
  • counts[word] reads the value stored under that key, and counts[word] = ... stores a new value under it, replacing the old one.
  • len(counts) is the number of keys, which here is the number of different words.

Check it worked

The output is 10 10 2 and then 36 different words. "It" and "was" each appear ten times in the first paragraph; "king" appears twice in the second. One hundred words, but only 36 different ones.

Step 3 · See KeyError, then avoid it with .get()

The if is there for a reason. Reading a key that does not exist is an error, and so is adding one to it. Run this two-line script to see what happens:

Bash
cat > broken.py <<'PY'
counts = {}
counts["it"] += 1
PY
python3 broken.py || echo "exit status $?"

counts["it"] += 1 means "read the value under it, add one, store it back". There is nothing under it to read, so Python stops with a traceback whose last line is KeyError: 'it', and the shell prints exit status 1. A KeyError always names the missing key, which tells you which lookup went wrong.

The .get() method is a lookup that never raises KeyError. Give it a default and it returns that when the key is missing. That turns the four-line if and else into one line:

Bash
cat > count_get.py <<'PY'
from words import read_words

counts = {}
for word in read_words("text.txt"):
    counts[word] = counts.get(word, 0) + 1

print(counts.get("queen"), counts.get("dragon"), counts.get("dragon", 0))

for word, number in counts.items():
    if number >= 4:
        print(word, number)
PY
python3 count_get.py
  • counts.get(word, 0) returns the current count, or 0 for a word not seen yet. Adding 1 gives the new count either way.
  • counts.get("dragon") with no default returns None, Python's value for "nothing". It does not crash, but None + 1 would, so pass a default when you plan to do arithmetic.
  • counts.items() gives you each key and value together, as a pair. for word, number in ... unpacks each pair into two variables, so you do not have to look the value up again inside the loop. The pairs come out in the order the keys were first added.

Check it worked

The first line is 2 None 0. Then come the six words seen at least four times, in the order they first appear in the text: it 10, was 10, the 12, of 12, a 8 and with 4.

Step 4 · Learn which values can be keys

Words are strings, and strings make good keys. Not every value can be a key, though. Python finds a key by turning it into a number called a hash, and that number must never change. So keys must be immutable: values that cannot be changed once made, such as strings, numbers and tuples. A list can be changed (you can append to it), so it cannot be a key:

Bash
cat > keys.py <<'PY'
visits = {}
visits[("Lagos", "Nigeria")] = 3
visits[("Accra", "Ghana")] = 1
print(visits[("Lagos", "Nigeria")])

visits[["Nairobi", "Kenya"]] = 2
PY
python3 keys.py || echo "exit status $?"

A tuple, written with round brackets, is like a list you cannot change. Here each key pairs a city with its country, which keeps two cities with the same name apart.

Check it worked

The script prints 3, then stops on the last line with a TypeError whose message ends unhashable type: 'list', and the shell prints exit status 1. "Unhashable" is Python's word for "cannot be a key". If you need a list-like key, turn it into a tuple first: tuple(["Nairobi", "Kenya"]).

Step 5 · Find the most common words

Counting is so common that Python ships a dictionary built for it: Counter from the collections module. Hand it a list and it does the whole loop for you. Its most_common() method returns the top entries, largest first:

Bash
cat > top_words.py <<'PY'
from collections import Counter

from words import read_words

counts = Counter(read_words("text.txt"))
for word, number in counts.most_common(10):
    print(f"{word:<8} {number:>3}")

print("---")
plain = dict(counts)
by_count = sorted(plain.items(), key=lambda pair: pair[1], reverse=True)
print(by_count[:3])
PY
python3 top_words.py
  • Counter(...) builds the counts in one line. A Counter is a dictionary underneath, so counts["the"], in and .items() all work, and a missing word gives 0 instead of a KeyError.
  • counts.most_common(10) returns a list of the ten most common (word, count) pairs. When several words have the same count, they keep the order in which they first appeared in the text.
  • f"{word:<8} {number:>3}" lines the output up: <8 pads the word to eight characters, aligned left, and >3 right-aligns the number in three.
  • The second half shows how to sort an ordinary dictionary by its values, which you need when you are not using Counter. sorted() takes the pairs from .items(). key=lambda pair: pair[1] tells it what to sort by: a lambda is a one-line function without a name, and this one takes a pair and returns its second item, the count. reverse=True puts the largest first.

Check it worked

You see ten aligned lines, starting with the 12, of 12, it 10, was 10, a 8 and with 4, then four words that appear twice: times, age, epoch and season. Other words also appear twice, such as king and queen, but these four come first in the text. After ---, the last line is [('the', 12), ('of', 12), ('it', 10)]: the same top three, found without Counter.

Step 6 · Count each paragraph separately with a nested dictionary

A dictionary's values can be anything, including other dictionaries. That gives you a nested dictionary: an outer one keyed by paragraph number, where each value is that paragraph's own word count:

Bash
cat > per_paragraph.py <<'PY'
from collections import Counter
from pathlib import Path

PUNCTUATION = ".,;:!?\"'()"

text = Path("text.txt").read_text(encoding="utf-8")
paragraphs = [p for p in text.split("\n\n") if p.strip()]

per_paragraph = {}
for number, paragraph in enumerate(paragraphs, start=1):
    counts = Counter()
    for raw in paragraph.split():
        word = raw.strip(PUNCTUATION).lower()
        if word:
            counts[word] += 1
    per_paragraph[number] = counts

print(per_paragraph[1]["was"], per_paragraph[2]["was"])
print(per_paragraph[2]["king"], per_paragraph[1]["king"])

for number, counts in per_paragraph.items():
    top_word, top_count = counts.most_common(1)[0]
    print(f"paragraph {number}: {counts.total()} words, top: {top_word} ({top_count})")
PY
python3 per_paragraph.py
  • text.split("\n\n") cuts the text at each blank line. "\n" is a line break, so two in a row mark a blank line. The square-bracket line keeps only the pieces that are not empty: it is a list comprehension, a one-line way to build a list with a loop and a condition.
  • enumerate(paragraphs, start=1) numbers the paragraphs 1, 2 and so on.
  • counts[word] += 1 works on a Counter even for a new word, because a missing key counts as 0. On a plain dictionary this was the line that raised KeyError.
  • per_paragraph[2]["king"] uses two lookups in a row: the first finds paragraph 2's Counter, the second finds king inside it.
  • counts.total() adds up all the counts in a Counter.

Check it worked

The output is:

Text
10 0
2 0
paragraph 1: 60 words, top: it (10)
paragraph 2: 40 words, top: a (8)

"Was" appears ten times in the first paragraph and never in the second; "king" is the other way round. The two paragraph totals add up to the 100 words you counted in the first step.

Step 7 · Build a word-count script for any text file

Put it together in one script that takes a file name, and optionally how many words to show, from the command line:

Bash
cat > wordcount.py <<'PY'
import sys
from collections import Counter
from pathlib import Path

PUNCTUATION = ".,;:!?\"'()[]"


def count_words(text):
    counts = Counter()
    for raw in text.split():
        word = raw.strip(PUNCTUATION).lower()
        if word:
            counts[word] += 1
    return counts


def main(argv):
    if len(argv) not in (2, 3):
        sys.exit("usage: wordcount.py <file> [how-many]")
    path = Path(argv[1])
    how_many = 10
    if len(argv) == 3:
        if not argv[2].isdigit():
            sys.exit("how-many must be a whole number")
        how_many = int(argv[2])

    try:
        text = path.read_text(encoding="utf-8")
    except FileNotFoundError:
        sys.exit(f"no such file: {path}")

    counts = count_words(text)
    print(f"{path.name}: {counts.total()} words, {len(counts)} different")
    for word, number in counts.most_common(how_many):
        print(f"{number:>5}  {word}")


main(sys.argv)
PY
python3 wordcount.py text.txt 5
  • sys.argv is the list of words typed on the command line. sys.argv[0] is the script's name, sys.argv[1] the file and sys.argv[2], if given, the number.
  • sys.exit("...") prints the message and stops with exit status 1, so a typo gives a clear sentence instead of a traceback.
  • isdigit() checks the number before int() converts it, so five gets a helpful message.
  • try and except FileNotFoundError catch a wrong file name and report it.

Now try it on text in other languages. lower() works on any alphabet, so Été and été count as one word:

Bash
cat > greetings.txt <<'TXT'
Habari yako? Habari nzuri.
Asante sana. Asante!
Été, été.
TXT
python3 wordcount.py greetings.txt
python3 wordcount.py missing.txt || echo "exit status $?"

Check it worked

The first run prints text.txt: 100 words, 36 different, then 12 the, 12 of, 10 it, 10 was and 8 a, with the numbers right-aligned. The second prints greetings.txt: 9 words, 6 different, with habari, asante and été at 2 and yako, nzuri and sana at 1. The last run prints no such file: missing.txt and exit status 1.

Run it on any UTF-8 text file you have, such as notes or an exported chat, with python3 wordcount.py <your-file> 20. Replace <your-file> with its path. Expect "the", "and" or their equivalents in your language at the top; real word-frequency tools often skip these with a list of "stop words", which you could add as a set of words to ignore.

If you want to keep the script, copy wordcount.py out of the folder first. Then delete the demo folder:

Bash
cd ~
rm -rf ~/word-count-demo

Next steps

Need this done for you?

Padding does this work for growing companies, from the first diagnosis to a system that keeps working.

Platform Engineering

Get new tutorials

New tutorials, about twice a month.