Python powers everything from quick automation scripts to production-grade machine learning pipelines. When something breaks in production but works perfectly on your laptop, the culprit is almost always a version mismatch. I have seen production incidents traced back to a single package being one patch version behind where it needed to be. The ability to quickly and accurately check Python module versions is not a nice-to-have skill. It is a core part of every Python engineer’s daily workflow.<\/p>\n
This article covers every practical method for checking Python package versions, from a single terminal command to programmatic checks inside your code. I walk through pip show, pip list, importlib.metadata, and __version__ attributes. I explain when to use each approach, what the common mistakes are, and how to integrate version checking into CI\/CD pipelines. By the end you will have a complete mental model for managing Python package versions in any environment you work in.<\/p>\n
pip show <\/code> for detailed info on any package<\/li>\n- Programmatic approach:<\/strong> Use
importlib.metadata.version('package')<\/code> inside Python code<\/li>\n- Overview all packages:<\/strong> Run
pip list<\/code> to see every installed package and version<\/li>\n- Export for sharing:<\/strong> Run
pip freeze > requirements.txt<\/code> to capture exact versions<\/li>\n- Python 3.8+ only:<\/strong> Use the
importlib.metadata<\/code> standard library, not pkg_resources<\/code><\/li>\n<\/ul>\npip show vs pip list vs importlib.metadata: Complete Comparison<\/h2>\n
\n\n\nMethod<\/th>\n Best For<\/th>\n Scope<\/th>\n Output Type<\/th>\n Availability<\/th>\n<\/tr>\n<\/thead>\n \n\npip show<\/code><\/td>\nDetailed info on one specific package<\/td>\n Single package<\/td>\n Formatted metadata (name, version, location, deps)<\/td>\n Any Python with pip<\/td>\n<\/tr>\n \npip list<\/code><\/td>\nQuick overview of entire environment<\/td>\n All packages<\/td>\n Simple two-column list (name + version)<\/td>\n Any Python with pip<\/td>\n<\/tr>\n \npip freeze<\/code><\/td>\nGenerating requirements.txt files<\/td>\n All packages<\/td>\n Name==Version format (pip-installable)<\/td>\n Any Python with pip<\/td>\n<\/tr>\n \nimportlib.metadata<\/code><\/td>\nProgrammatic version checks inside code<\/td>\n Single or all packages<\/td>\n Python strings and objects<\/td>\n Python 3.8+ (stdlib)<\/td>\n<\/tr>\n \n__version__ attribute<\/code><\/td>\nQuick one-liners for packages that support it<\/td>\n Single package<\/td>\n String version<\/td>\n Only packages that define it<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\nWhy Does Checking Python Module Versions Matter in Production?<\/h2>\n
Every senior engineer has been there. You ship code to production and it breaks because the deployment environment has a different package version than your local machine. The requests<\/code> library changed an API between 2.28 and 2.31. NumPy dropped support for a deprecated array creation function. Your CI passed but production fails.<\/p>\nVersion mismatches are among the top causes of production incidents in Python applications. When you have dozens of direct dependencies and hundreds of transitive dependencies, tracking what version is where becomes a full-time job. The tools I am about to show you are the first line of defense.<\/p>\n
Beyond incident prevention, version checking matters for security. The requests<\/code> library alone has had multiple CVEs fixed in point releases. If you do not know what version you are running, you cannot know if you are exposed. Running pip list --outdated<\/code> periodically is not paranoia. It is standard engineering practice.<\/p>\nDependency confusion attacks are another reason to verify versions. An attacker publishes a malicious package with the same name as an internal package to a public index. If your environment resolves to the wrong version, you have a supply chain problem. Knowing exactly which version you have installed is the foundation of defending against this class of attack.<\/p>\n
How Do I Check a Specific Package Version with pip show?<\/h2>\n
The most direct way to get detailed information about a single package is pip show<\/code>. Run it from your terminal with the package name and you get everything: version, home page, author, license, installation location, direct dependencies, and which other packages depend on it.<\/p>\nHere is the command:<\/p>\n
pip show <\/pre>\nFor example, to check the requests library:<\/p>\n
pip show requests<\/pre>\nThe output looks like this:<\/p>\n
Name: requests\nVersion: 2.31.0\nSummary: Python HTTP for Humans.\nHome-page: https:\/\/requests.readthedocs.io\nAuthor: Kenneth Reitz\nAuthor-email: me@kennethreitz.org\nLicense: Apache 2.0\nLocation: \/usr\/local\/lib\/python3.11\/site-packages\nRequires: charset-normalizer, idna, urllib3, certifi\nRequired-by: botocore, boto3<\/pre>\nNotice that the output tells you not just the version but also what requests<\/code> requires and what depends on it. That Required-by<\/code> field is useful when you are trying to figure out why a package is installed at all.<\/p>\nIf you want just the version number and nothing else, pipe the output through grep<\/code> or awk<\/code>:<\/p>\npip show requests | grep Version\n# Or on Unix:\npip show requests | awk '\/Version:\/ {print $2}'<\/pre>\nOn Windows, you can use findstr<\/code>:<\/p>\npip show requests | findstr Version<\/pre>\nFor CI\/CD pipelines where you need to validate versions programmatically, use the --format=json<\/code> flag (pip 22.0+):<\/p>\npip show requests --format=json<\/pre>\nThis gives you a JSON object you can parse in any language:<\/p>\n
{\n \"name\": \"requests\",\n \"version\": \"2.31.0\",\n \"summary\": \"Python HTTP for Humans.\",\n \"home_page\": \"https:\/\/requests.readthedocs.io\",\n \"author\": \"Kenneth Reitz\",\n \"author_email\": \"me@kennethreitz.org\",\n \"license\": \"Apache 2.0\",\n \"location\": \"\/usr\/local\/lib\/python3.11\/site-packages\",\n \"requires\": [\"charset-normalizer\", \"idna\", \"urllib3\", \"certifi\"],\n \"required_by\": [\"botocore\", \"boto3\"]\n}<\/pre>\nHow Do I Check All Installed Package Versions at Once?<\/h2>\n
Sometimes you need the full picture. pip list<\/code> shows every package installed in the current environment in a simple two-column format:<\/p>\npip list<\/pre>\nThe output looks like this:<\/p>\n
Package Version\n--------------- ---------\npip 24.0\nsetuptools 69.5.1\nwheel 0.43.0\nrequests 2.31.0\nnumpy 1.26.3\npandas 2.1.4<\/pre>\nIf you are working in a virtual environment, pip list<\/code> only shows packages in that environment. That is exactly what you want. Never check versions in the wrong environment.<\/p>\nTo find outdated packages, use the --outdated<\/code> flag. This is the command I run every morning before touching any codebase:<\/p>\npip list --outdated<\/pre>\nTo get output in a format suitable for requirements.txt<\/code>, use pip freeze<\/code>:<\/p>\npip freeze<\/pre>\nThis gives you output in package==version<\/code> format that you can redirect to a file:<\/p>\npip freeze > requirements.txt<\/pre>\nYou can then install exact versions in a fresh environment with:<\/p>\n
pip install -r requirements.txt<\/pre>\nNote that pip freeze<\/code> includes every package pip knows about, including pip itself and setuptools. Often you want only direct dependencies. Use pipreqs<\/code> or pip-chill<\/code> for that:<\/p>\npip install pip-chill\npip-chill<\/pre>\nHow Do I Check Python Package Versions Inside My Code?<\/h2>\n
There are cases where you need to check a package version from within Python code itself. Maybe you are building a library that needs to behave differently depending on the NumPy version. Maybe you are writing a setup script that validates the environment before proceeding. For these cases, importlib.metadata<\/code> is the right tool.<\/p>\nFor Python 3.8 and newer, the standard library includes importlib.metadata<\/code>. It reads package metadata from the .dist-info<\/code> directories that pip creates when installing packages:<\/p>\nfrom importlib.metadata import version\n\nrequests_version = version('requests')\nprint(f\"Requests version: {requests_version}\")<\/pre>\nThe version()<\/code> function returns the version as a string. It is simple and reliable:<\/p>\nfrom importlib.metadata import version\n\npackages = ['requests', 'numpy', 'pandas', 'django', 'flask']\nfor pkg in packages:\n try:\n ver = version(pkg)\n print(f\"{pkg}=={ver}\")\n except Exception as e:\n print(f\"{pkg}: not found ({e})\")<\/pre>\nTo list all installed packages programmatically, use the distributions()<\/code> function:<\/p>\nfrom importlib.metadata import distributions\n\nfor dist in distributions():\n name = dist.metadata['Name']\n ver = dist.version\n print(f\"{name}=={ver}\")<\/pre>\nThis is equivalent to pip freeze<\/code> but gives you Python objects you can filter, sort, or serialize as needed.<\/p>\nFor Python 3.7 and earlier, importlib.metadata<\/code> is not in the standard library. You have two options. The first is to use the backport:<\/p>\npip install importlib-metadata\nfrom importlib_metadata import version\n\nver = version('requests')\nprint(f\"Requests version: {ver}\")<\/pre>\nThe second option is to fall back to the older pkg_resources<\/code> module from setuptools:<\/p>\nimport pkg_resources\n\nrequests_version = pkg_resources.get_distribution('requests').version\nprint(f\"Requests version: {requests_version}\")<\/pre>\nThat said, pkg_resources<\/code> is deprecated and slower. If at all possible, upgrade to Python 3.8 or newer and use importlib.metadata<\/code>.<\/p>\nWhat About the __version__ Attribute? Does That Still Work?<\/h2>\n
Many Python packages expose a __version__<\/code> attribute on the module. NumPy does it, Django does it, many others too:<\/p>\nimport numpy as np\nprint(np.__version__)\n# Output: 1.26.3\n\nimport django\nprint(django.__version__)\n# Output: 5.0.1\n\nimport requests\nprint(requests.__version__)\n# Output: 2.31.0<\/pre>\nThis approach works but it is a convention, not a standard. Some packages use __version__<\/code>, others use VERSION<\/code>, others use version<\/code> as a module-level constant. Some packages do not expose a version attribute at all.<\/p>\nIf you are writing a library that needs to check the version of a dependency, importlib.metadata.version()<\/code> is more reliable than trying to access __version__<\/code>. It handles the inconsistencies across packages. Here is why:<\/p>\n# Unreliable - package might not have __version__\nimport somelib\nprint(somelib.__version__) # AttributeError if not defined\n\n# Reliable - always works if package is installed\nfrom importlib.metadata import version, PackageNotFoundError\ntry:\n ver = version('somelib')\n print(ver)\nexcept PackageNotFoundError:\n print(\"somelib is not installed\")<\/pre>\nThe importlib.metadata<\/code> approach is also faster because it reads metadata from the installed package files rather than importing the entire module.<\/p>\nHow Do I Check Python Module Version for Popular Packages?<\/h2>\n
Let me give you concrete examples for the packages I see most often in production environments.<\/p>\n
NumPy<\/h3>\n# Command line\npip show numpy\n\n# Inside Python\nfrom importlib.metadata import version\nprint(version('numpy'))\n\n# Module attribute\nimport numpy as np\nprint(np.__version__)<\/pre>\nAll three approaches give the same result. The importlib.metadata<\/code> approach is what I recommend for scripts because it does not require importing the entire NumPy library just to check a version string.<\/p>\nPandas<\/h3>\n# Command line\npip show pandas\n\n# Inside Python\nfrom importlib.metadata import version\nprint(version('pandas'))\n\n# Module attribute\nimport pandas as pd\nprint(pd.__version__)<\/pre>\nDjango<\/h3>\n# Command line\npip show django\n\n# Inside Python\nfrom importlib.metadata import version\nprint(version('django'))\n\n# Module attribute\nimport django\nprint(django.__version__)<\/pre>\nRequests<\/h3>\n# Command line\npip show requests\n\n# Inside Python\nfrom importlib.metadata import version\nprint(version('requests'))\n\n# Module attribute\nimport requests\nprint(requests.__version__)<\/pre>\nTensorFlow<\/h3>\n# Command line\npip show tensorflow\n\n# Inside Python\nfrom importlib.metadata import version\nprint(version('tensorflow'))\n\n# Module attribute\nimport tensorflow as tf\nprint(tf.__version__)<\/pre>\nPyTorch<\/h3>\n# Command line\npip show torch\n\n# Inside Python\nfrom importlib.metadata import version\nprint(version('torch'))\n\n# Module attribute\nimport torch\nprint(torch.__version__)<\/pre>\nHow Do I Check Python Module Version in Different Environments?<\/h2>\nVirtual Environments<\/h3>\n
Always check versions in the correct virtual environment. Activate your environment first, then run pip commands. The version you see depends entirely on which environment is active:<\/p>\n
# Create and activate\npython -m venv myenv\nsource myenv\/bin\/activate # Linux\/Mac\n# myenv\\Scripts\u0007ctivate # Windows\n\n# Now check versions\npip show numpy<\/pre>\nIf you see unexpected versions, verify your environment is active. Run which python<\/code> (Unix) or where python<\/code> (Windows) to confirm which interpreter you are using.<\/p>\nDocker Containers<\/h3>\n
Inside a Docker container, the workflow is the same. Build your image, run a container, activate the environment if applicable, then check versions:<\/p>\n
docker run -it myimage \/bin\/bash\nsource \/venv\/bin\/activate\npip show numpy<\/pre>\nFor a one-liner without shell access:<\/p>\n
docker exec mycontainer pip show numpy<\/pre>\nJupyter Notebooks<\/h3>\n
Jupyter has its own kernel and its own environment. If you are running Jupyter inside a virtual environment, pip show<\/code> from a terminal might show different results than running importlib.metadata<\/code> inside a notebook cell. Always check from within the notebook kernel you are actually using:<\/p>\n# In a Jupyter cell\nfrom importlib.metadata import version\nprint(version('numpy'))\nprint(version('pandas'))<\/pre>\nCI\/CD Pipelines<\/h3>\n
In GitHub Actions, GitLab CI, or similar, always validate versions as part of your pipeline to catch environment drift:<\/p>\n
# In a CI job\n- name: Check critical package versions\n run: |\n pip show numpy | grep Version\n pip show pandas | grep Version\n pip show django | grep Version<\/pre>\nYou can also use a Python script in your CI to validate against a known-good version:<\/p>\n
from importlib.metadata import version\nimport sys\n\nrequired = {\n 'numpy': '1.26.0',\n 'pandas': '2.1.0',\n}\n\nfor pkg, min_ver in required.items():\n installed = version(pkg)\n if installed < min_ver:\n print(f\"FAIL: {pkg} {installed} < {min_ver}\")\n sys.exit(1)\n print(f\"OK: {pkg} {installed}\")<\/pre>\nWhat Are the Most Common Mistakes When Checking Python Package Versions?<\/h2>\nMistake 1: Checking the wrong environment<\/h3>\n
The most common mistake is running pip show<\/code> in one environment but importing in another. Python always uses the interpreter that runs the code. If you have multiple Python installations or virtual environments, they have independent package stores. Always verify which environment you are in:<\/p>\n# Always do this first\nimport sys\nprint(sys.executable)\nprint(sys.prefix)<\/pre>\nMistake 2: Relying on __version__ without fallback<\/h3>\n
The __version__<\/code> attribute is not guaranteed to exist. Packages change their attributes, some packages use different names, and some packages do not expose version at the module level at all. Always handle the missing case:<\/p>\nimport somelib\n\n# This will crash if __version__ is not defined\n# print(somelib.__version__)\n\n# Safer approach using importlib.metadata\nfrom importlib.metadata import version, PackageNotFoundError\ntry:\n print(version('somelib'))\nexcept PackageNotFoundError:\n print(\"somelib not installed\")<\/pre>\nMistake 3: Using pkg_resources in new code<\/h3>\n
The pkg_resources<\/code> module from setuptools is deprecated. It is slow because it scans the entire environment on import. importlib.metadata<\/code> is faster, is part of the standard library, and is the future. Migrate any old code that uses pkg_resources<\/code>:<\/p>\n# Old (deprecated)\nimport pkg_resources\nver = pkg_resources.get_distribution('requests').version\n\n# New (standard library)\nfrom importlib.metadata import version\nver = version('requests')<\/pre>\nMistake 4: Forgetting that pip list shows ALL packages<\/h3>\n
pip list<\/code> shows every package pip knows about, including pip itself, setuptools, wheel, and any other packages that came with your Python distribution. When generating requirements.txt<\/code>, you usually want only your application dependencies. Use pip-chill<\/code> or manually filter the output:<\/p>\n# Only top-level dependencies, not transitive ones\npip-chill --no-chill<\/pre>\nHow Do I Verify Python Module Version in Requirements Files?<\/h2>\n
Requirements files are static snapshots of your environment at a point in time. Over time, the packages listed in a requirements.txt<\/code> may drift from what is actually installed. Here is how to audit the gap:<\/p>\n# Generate current freeze\npip freeze > current.txt\n\n# Compare with your requirements\ndiff requirements.txt current.txt<\/pre>\nFor a more structured approach, use pip-tools<\/code>:<\/p>\n# Install pip-tools\npip install pip-tools\n\n# Generate a locked requirements file\npip-compile requirements.in\n\n# This creates requirements.txt with pinned versions\n# that satisfy all constraints in requirements.in<\/pre>\nFor checking specific package versions against requirements:<\/p>\n
# Check if numpy is at least version 1.26\nfrom importlib.metadata import version\nfrom packaging import version as pkg_version\n\ninstalled = version('numpy')\nrequired = '1.26.0'\n\nif pkg_version.parse(installed) < pkg_version.parse(required):\n print(f\"FAIL: numpy {installed} < required {required}\")\nelse:\n print(f\"OK: numpy {installed}\")<\/pre>\nThe packaging<\/code> library handles version comparison correctly, accounting for pre-releases, dev releases, and post-releases in a way that string comparison cannot.<\/p>\nQuick Reference: Python Module Version Check Commands<\/h2>\n
\n\n\nTask<\/th>\n Command<\/th>\n Notes<\/th>\n<\/tr>\n<\/thead>\n \n\nCheck specific package (terminal)<\/td>\n pip show <\/code><\/td>\nFull metadata output<\/td>\n<\/tr>\n \nCheck specific package (terminal, version only)<\/td>\n pip show | grep Version<\/code><\/td>\nQuick one-liner<\/td>\n<\/tr>\n \nList all packages (terminal)<\/td>\n pip list<\/code><\/td>\nTwo-column output<\/td>\n<\/tr>\n \nFind outdated packages (terminal)<\/td>\n pip list --outdated<\/code><\/td>\nUseful for maintenance<\/td>\n<\/tr>\n \nGenerate requirements file (terminal)<\/td>\n pip freeze > requirements.txt<\/code><\/td>\nExact version pins<\/td>\n<\/tr>\n \nCheck version in Python code<\/td>\n importlib.metadata.version('name')<\/code><\/td>\nPython 3.8+<\/td>\n<\/tr>\n \nCheck via module attribute<\/td>\n import pkg; print(pkg.__version__)<\/code><\/td>\nOnly if package defines it<\/td>\n<\/tr>\n \nList all packages in Python<\/td>\n importlib.metadata.distributions()<\/code><\/td>\nProgrammatic equivalent of pip freeze<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n\nHow do I check the version of a specific Python module?<\/h3>\n\nRun pip show <module-name><\/code> from your terminal for full metadata including version, author, license, and dependencies. Alternatively, use import importlib.metadata; print(importlib.metadata.version('module-name'))<\/code> inside any Python script. Both approaches work reliably for every package installed via pip, and neither requires you to import the package itself.<\/p>\n<\/div>\nWhat is the difference between pip list and pip freeze?<\/h3>\n\npip list<\/code> displays all installed packages in a simple two-column table showing name and version. pip freeze<\/code> outputs packages in name==version<\/code> format that you can redirect directly into a requirements.txt file for environment recreation. Use pip list for quick human-readable overviews. Use pip freeze when you need to capture exact versions for sharing or deployment.<\/p>\n<\/div>\nWhich Python version introduced importlib.metadata?<\/h3>\n\n