---
id: titlecase
version: "2.4.1"
license: MIT
license_treatment: permissive
maintenance: aging
---

# titlecase — Python Port of John Gruber's titlecase.pl

License: permissive · Maintenance: aging · Downloads: 691.2K/mo

## What it is and what it does

Titlecase is a text formatting library that converts strings to title case while intelligently preserving small words (a, an, the, and, or, etc.) in lowercase based on New York Times style conventions. It also attempts to detect and preserve acronyms and abbreviations that are already in all caps. The library provides both a Python API and a command-line tool, making it useful for one-off conversions or integration into larger text-processing pipelines.

The package has no runtime dependencies and supports Python 3.7, 3.8, 3.9, and 3.10. It uses regex-based heuristics to handle edge cases, though it acknowledges limitations with contextual awareness (e.g., distinguishing 'us' the pronoun from 'US' the country) and non-English text. The library is a modern port of John Gruber's original titlecase.pl Perl script, maintained on GitHub with a stable user base.

Use it for:

- Format user-generated titles or headlines in web applications before display or storage.
- Batch-process document titles or CSV headers from the command line using the titlecase utility.
- Normalize book, article, or product names in data pipelines while preserving common acronyms via callback functions.
- Convert all-caps or mixed-case text to consistent title formatting in content management systems.
- Implement custom capitalization rules for domain-specific acronyms by providing a callback function.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Converts text to title case with intelligent handling of small words (a, an, the) based on New York Times style rules, plus a command-line utility for batch processing.

Yes, if you need reliable title-case conversion with sensible English-language defaults and don't require frequent updates. The high install friction (source-only distribution) and aging maintenance status are acceptable trade-offs for a stable, single-purpose utility with no dependencies. Not recommended if you need active bug fixes or compatibility guarantees beyond Python 3.10.

## Install

pip install titlecase
uv add titlecase
poetry add titlecase

## Installing titlecase

Before you install: High install friction due to source-only distribution (no wheels). The package is in aging maintenance status—last release was 2023-09-23, over a year ago—though the repository remains active and the code is marked Production/Stable. Suitable for stable, non-critical text processing tasks where you don't expect frequent updates.

License in practice: MIT license (permissive) means you can use, modify, and distribute this package freely in commercial and private projects with minimal restrictions, provided you include the license notice.

Quickstart:

pip install titlecase

from titlecase import titlecase
result = titlecase('a thing')
print(result)  # 'A Thing'

# With callback for custom handling:
def abbreviations(word, **kwargs):
    if word.upper() in ('TCP', 'UDP'):
        return word.upper()

result = titlecase('a simple tcp and udp wrapper', callback=abbreviations)
print(result)  # 'A Simple TCP and UDP Wrapper'

Requires Python 3.7 or later. Source distribution only (no wheels), so installation requires a working C compiler and development headers if your environment lacks pre-built packages.

Verify before relying:

- Whether the aging maintenance status poses a risk for Python 3.11+ compatibility or future standard library changes.
- Performance characteristics on very large texts or in high-throughput scenarios.
- Whether Unicode handling beyond basic accented characters (e.g., non-Latin scripts) is sufficient for your use case.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: high
- Maintenance: aging
- Downloads: 691.2K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

title case conversion, titlecase formatting, smart capitalization, text title casing, command line title case, small words capitalization, title formatting tool, text-formatting, cli-tool, english-language

[View on SkillFed](https://skillfed.io/packages/titlecase) · [View on PyPI](https://pypi.org/project/titlecase/)