pypa/pip · error · CommandError

List format 'freeze' cannot be used with the --outdated opti

Error message

List format 'freeze' cannot be used with the --outdated option.

What it means

Raised as CommandError in ListCommand.run() at list.py:179-182 when --outdated is combined with --format freeze. The freeze format emits 'name==version' requirement lines, which is incompatible with the extra Latest/Type columns that --outdated produces; pip forbids the combination to avoid ambiguous output.

Source

Thrown at src/pip/_internal/commands/list.py:180

            release_control=options.release_control,
            format_control=options.format_control,
            prefer_binary=options.prefer_binary,
        )

        return PackageFinder.create(
            link_collector=link_collector,
            selection_prefs=selection_prefs,
            uploaded_prior_to=options.uploaded_prior_to,
        )

    def run(self, options: Values, args: list[str]) -> int:
        cmdoptions.check_release_control_exclusive(options)

        if options.outdated and options.uptodate:
            raise CommandError("Options --outdated and --uptodate cannot be combined.")

        if options.outdated and options.list_format == "freeze":
            raise CommandError(
                "List format 'freeze' cannot be used with the --outdated option."
            )

        cmdoptions.check_list_path_option(options)

        packages: _ProcessedDists = [
            cast("_DistWithLatestInfo", d)
            for d in get_environment(options.path).iter_installed_distributions(
                local_only=options.local,
                user_only=options.user,
                editables_only=options.editable,
                include_editables=options.include_editable,
                skip=set(stdlib_pkgs),
            )
        ]

        # get_not_required must be called firstly in order to find and
        # filter out all dependencies correctly. Otherwise a package

View on GitHub (pinned to d7d0d0a394)

Solutions

Use --format json with --outdated, which includes version AND latest_version fields.
Use --format columns (default) with --outdated to see the Latest/Type columns.
Drop --outdated if you specifically need freeze output.

Example fix

# before
pip list --outdated --format freeze
# after
pip list --outdated --format json

Defensive patterns

Strategy: validation

Validate before calling

import sys
fmt = None
for i,a in enumerate(sys.argv):
    if a == '--format' and i+1 < len(sys.argv):
        fmt = sys.argv[i+1]
    elif a.startswith('--format='):
        fmt = a.split('=',1)[1]
outdated = ('--outdated' in sys.argv) or ('-o' in sys.argv)
if outdated and fmt == 'freeze':
    print('ERROR: --format freeze cannot be combined with --outdated; use --format json', file=sys.stderr)
    sys.exit(2)

Prevention

Use --format json with --outdated for machine-readable output.
Reserve --format freeze for full environment snapshots without --outdated.

When it happens

Trigger: Running 'pip list -o --format freeze' or 'pip list --outdated --format=freeze'. The check at list.py:179 matches options.outdated and options.list_format == 'freeze'.

Common situations: Wanting a freeze-style list of only outdated packages; script authors combining the audit flag with the machine-friendly format.

Related errors

AI-assisted analysis of pypa/pip@d7d0d0a394 (2026-08-04). Data as JSON: /data/errors/d7af692417dfadec.json. Report an issue: GitHub.