Introduction

This import error usually means the code is depending on an internal symbol that is not available in the installed version of the contractions package. The safest fix is usually to stop importing CONTRACTION_MAP directly and use the package’s public API instead, unless you intentionally control and pin a version that exposes that constant.

Why the Import Fails

There are several common causes:

• the installed package version never exported CONTRACTION_MAP
• an older tutorial referenced an internal object that is no longer public
• a local file named contractions.py is shadowing the package
• the code is running in a different environment from the one where the package was installed

The main lesson is that package internals are much less stable than documented public functions.

Inspect What Python Is Actually Importing

Before changing code, inspect the module path and installed version.

1import contractions
2import importlib.metadata as md
3
4print("module path:", contractions.__file__)
5print("version:", md.version("contractions"))
6print("has CONTRACTION_MAP:", hasattr(contractions, "CONTRACTION_MAP"))
7print("exports:", [name for name in dir(contractions) if "fix" in name.lower() or "map" in name.lower()])

If the module path points inside your project instead of site-packages, you likely have a shadowing problem. If the version differs from the one in the example you copied, the symbol may simply not exist there.

Prefer the Public Function

For most text-normalization tasks, the public function is what you actually need.

1import contractions
2
3samples = [
4    "I can't do it.",
5    "She's sure it'll work.",
6    "We've already tried.",
7]
8
9for text in samples:
10    print(contractions.fix(text))

This is better than importing CONTRACTION_MAP because contractions.fix(...) is the supported behavior the package is designed to expose.

Define Your Own Map If You Need Fixed Rules

Sometimes you do not want library-defined behavior at all. If you need reviewable and stable expansion rules, define your own mapping explicitly.

1import re
2
3CUSTOM_MAP = {
4    "can't": "cannot",
5    "won't": "will not",
6    "I've": "I have",
7    "it's": "it is",
8}
9
10pattern = re.compile("|".join(re.escape(k) for k in CUSTOM_MAP))
11
12
13def expand_custom(text: str) -> str:
14    return pattern.sub(lambda m: CUSTOM_MAP[m.group(0)], text)
15
16
17print(expand_custom("I've seen it and it's fine, but it can't wait."))

That gives you deterministic behavior that will not drift when a dependency changes.

Pin a Version Only Deliberately

If your codebase really needs a version that exposes CONTRACTION_MAP, pin it explicitly and document why.

python -m pip install 'contractions==0.1.73'
python -m pip show contractions

But do this only if you have confirmed that the version truly exports the symbol and that your project intentionally depends on it. Pinning blindly just freezes the problem into your environment.

Environment Mismatch Is Common

This error shows up frequently in notebooks, virtual environments, and CI systems because the code is tested in one interpreter and run in another. If the import works in a shell but fails in a notebook, check the active interpreter there too.

import sys
print(sys.executable)

That small check often reveals that the package was installed in one environment and imported from another.

Common Pitfalls

• Copying an import from a tutorial without checking the installed package version.
• Importing a private or version-specific symbol instead of using the public API.
• Shadowing the real package with a local file or directory named contractions.
• Pinning an old version as a quick fix without documenting the dependency choice.
• Debugging only the shell environment instead of the actual interpreter running the code.

Summary

• 'CONTRACTION_MAP import errors usually come from version mismatch, shadowing, or reliance on internal package symbols.'
• Inspect the module path and installed package version before changing code.
• Prefer contractions.fix(...) over importing internal constants.
• Use your own mapping if you need stable, explicit expansion rules.
• Pin package versions only when that compatibility choice is intentional and documented.