How to Check Python Package Version

Knowing the exact version of installed libraries is essential for reproducibility, debugging, and ensuring compatibility. Whether you are working in the terminal or writing a script, Python provides standard tools to retrieve this information.

This guide covers the best methods to check package versions: terminal commands, Python code, and outdated package detection.

Using the Terminal (CLI)

When investigating an environment or troubleshooting issues, pip commands provide quick access to version information.

Check a Specific Package

Use pip show to get detailed metadata about a single installed package:

pip show pandas

Output:

Name: pandas
Version: 2.1.4
Summary: Powerful data structures for data analysis...
Home-page: https://pandas.pydata.org
Author: The Pandas Development Team
License: BSD-3-Clause
Location: /usr/local/lib/python3.11/site-packages
Requires: numpy, python-dateutil, pytz
Required-by: seaborn, statsmodels

List All Packages

Use pip list to display a table of all installed packages with their versions:

pip list

Output:

Package         Version
--------------- -------
numpy           1.26.2
pandas          2.1.4
requests        2.31.0

Export for Deployment

Use pip freeze to generate output suitable for a requirements.txt file:

pip freeze > requirements.txt

tip

The pip freeze format (package==version) is ideal for pinning exact versions in production environments, ensuring consistent deployments.

Using Python Code

When your script needs to verify versions at runtime, for example, to check compatibility, use Python's import system.

The Modern Way: importlib.metadata (Recommended)

Since Python 3.8, the standard library provides importlib.metadata. This method retrieves version information without importing the package itself.

from importlib.metadata import version

# Fast and safe: doesn't load the package into memory
pandas_ver = version("pandas")
print(f"Pandas version: {pandas_ver}")

# Check multiple packages
packages = ["numpy", "requests", "pandas"]
for pkg in packages:
    try:
        print(f"{pkg}: {version(pkg)}")
    except Exception:
        print(f"{pkg}: not installed")

Version Comparison

For scripts that require minimum versions:

from importlib.metadata import version
from packaging.version import Version

pandas_ver = Version(version("pandas"))

if pandas_ver >= Version("2.0.0"):
    print("Using modern Pandas API")
else:
    print("Legacy Pandas version detected")

note

The packaging library provides robust version comparison. Install it with pip install packaging if not already available.

The Classic Way: __version__ Attribute

Most libraries expose a __version__ attribute, though this approach has drawbacks:

import pandas

# Requires loading the entire package first
print(pandas.__version__)

caution

Prefer importlib.metadata over __version__. Accessing the attribute requires importing the library, which may fail if dependencies are missing or cause unnecessary overhead for large packages.

Finding Outdated Packages

Regularly checking for updates helps maintain security and access new features.

pip list --outdated

Output:

Package    Version   Latest    Type
---------- --------- --------- -----
numpy      1.24.0    1.26.2    wheel
requests   2.28.1    2.31.0    wheel
urllib3    1.26.12   2.1.0     wheel

Upgrade Outdated Packages

To upgrade a specific package:

pip install --upgrade numpy

To upgrade all outdated packages (use with caution):

pip list --outdated --format=freeze | cut -d= -f1 | xargs -n1 pip install --upgrade

danger

Upgrading all packages at once can introduce breaking changes. Always test in a development environment first and review changelogs for major version updates.

Checking Versions in Virtual Environments

When working with multiple projects, ensure you are checking the correct environment:

# Verify which pip you are using
which pip

# Or check the Python environment directly
python -m pip show pandas

Summary

Goal	Method	Context
Get details of one package	pip show <name>	Terminal
List all installed packages	pip list	Terminal
Export versions for deployment	pip freeze	Terminal
Check version in code	importlib.metadata.version()	Python script
Find outdated packages	pip list --outdated	Terminal

Best Practice

Use importlib.metadata.version() for runtime version checks in scripts. It avoids importing heavy libraries and works consistently across all packages. For quick terminal checks, pip show provides the most detailed information.