Analyzing Repository Composition with pygount

pygount is a command-line tool that scans directories and reports lines of code, language breakdown, file counts, and code-vs-comment ratios. It uses the pygount library to detect programming languages and classify each line as code, comment, or empty.

When to Use pygount

Use pygount when someone asks for:

• Lines of code (LOC) count for a repository
• A language breakdown showing which languages are used and how much
• Codebase size or composition, including file counts
• Code-vs-comment ratios
• General "how big is this repo" questions

Prerequisites

Install pygount with this command:

pip install --break-system-packages pygount 2>/dev/null || pip install pygount

The first attempt tries the --break-system-packages flag for modern pip environments; if it fails, the fallback is a standard install.

Basic Summary (Most Common)

The most common workflow produces a summary table of all languages found in a repository. Change to the repository root first, then run:

cd /path/to/repo
pygount --format=summary \
  --folders-to-skip=".git,node_modules,venv,.venv,__pycache__,.cache,dist,build,.next,.tox,.eggs,*.egg-info" \
  .

The --folders-to-skip parameter is strongly recommended to avoid crawling dependency directories, which can cause long runtimes or hangs. The . argument tells pygount to scan the current directory.

Filtering by Specific Language

Use the --suffix parameter to limit scanning to one or more file extensions.

# Only count Python files
pygount --suffix=py --format=summary .

# Only count Python and YAML
pygount --suffix=py,yaml,yml --format=summary .

The --suffix value is a comma-separated list of extensions (without leading dots). This is useful for large monorepos where scanning everything would be slow.

Detailed File-by-File Output

The default output format (without --format) shows a per-file breakdown. This can be piped to sort and head for custom views.

# Default format shows per-file breakdown
pygount --folders-to-skip=".git,node_modules,venv" .

# Sort by code lines (pipe through sort)
pygount --folders-to-skip=".git,node_modules,venv" . | sort -t$'\t' -k1 -nr | head -20

The sort command uses tab as the field separator and sorts numerically by the first column (code lines), showing the top 20 files.

Output Formats

pygount supports three output formats:

# Summary table (default recommendation)
pygount --format=summary .

# JSON output for programmatic use
pygount --format=json .

# Pipe-friendly: Language, file count, code, docs, empty, string
pygount --format=summary . 2>/dev/null

• summary: A table with columns for language, file count, code lines, documentation lines, empty lines, and string lines.
• json: Machine-readable JSON output.
• default (no --format): File-by-file listing.

The pipe-friendly variant suppresses stderr with 2>/dev/null for cleaner output when piping.

Parameters

Parameter	Meaning	Required
--format	Output format: summary, json, or default (file-by-file)	No (default is file-by-file)
--folders-to-skip	Comma-separated list of folder names to exclude	Strongly recommended
--suffix	Comma-separated list of file extensions to include (e.g., py, yaml)	No
.	Path to the directory to scan (usually current directory)	Yes

Special Pseudo-Languages

pygount detects several special categories that appear as languages in the output:

• __empty__ – empty files
• __binary__ – binary files
• __generated__ – auto-generated files
• __duplicate__ – files that appear to be duplicates
• __unknown__ – files whose language could not be determined

Recommended Folder Exclusion Patterns

Different project types benefit from different skip lists. These examples show common patterns:

# Python projects
--folders-to-skip=".git,venv,.venv,__pycache__,.cache,dist,build,.tox,.eggs,.mypy_cache"

# JavaScript/TypeScript projects
--folders-to-skip=".git,node_modules,dist,build,.next,.cache,.turbo,coverage"

# General catch-all
--folders-to-skip=".git,node_modules,venv,.venv,__pycache__,.cache,dist,build,.next,.tox,vendor,third_party"

Constraints and Caveats

• Always use --folders-to-skip to exclude .git, node_modules, venv, and similar directories. Without it, pygount may take minutes or hang on large dependency trees.
• Markdown files show 0 code lines because all content is classified as comments.
• JSON files may show low code counts. For accurate JSON line counts, use wc -l directly.
• For large monorepos, consider using --suffix to target specific languages instead of scanning everything.

Failure Modes

• Missing --folders-to-skip: pygount may take minutes or hang on large dependency trees.
• Markdown: Content is not counted as code (this is expected behavior).
• JSON: Line counts may be conservative; use wc -l for precise counts.