Understanding Python Dependency Versioning Symbols

Hi all,

It's been so confusing for me when the versions are with different operators.

Introduction: Managing dependencies in Python is crucial for ensuring your project runs smoothly across different environments. Dependencies, or libraries your project relies on, often need specific versions to maintain compatibility. This blog post will walk you through the symbols used in Python versioning and how they work to keep your project stable and functional.

What Are Python Dependencies?

In Python projects, dependencies are essential libraries that your project needs to function. They’re often listed in files like requirements.txt or Pipfile. To keep these dependencies compatible, Python uses specific symbols in versioning to define acceptable package versions. Let's dive into each symbol to see how they impact dependency management.

Key Python Versioning Symbols

1. Exact Version (==)

   • Syntax: package_name==1.0.0
   • Meaning: Installs only the specified version. For example, numpy==1.18.5 installs version 1.18.5 of NumPy.
   • Best For: Strict requirements when a specific version is necessary for compatibility.

2. Minimum Version (>=)

   • Syntax: package_name>=1.0.0
   • Meaning: Installs the specified version or newer. Example: Django>=3.1.0 installs any version of Django from 3.1.0 onward.
   • Best For: Ensuring updates without breaking compatibility with older versions.

3. Maximum Version (<=)

   • Syntax: package_name<=1.0.0
   • Meaning: Installs only the specified version or older. For example, pandas<=1.2.3 won’t install any version beyond 1.2.3.
   • Best For: Avoiding potential incompatibilities with newer versions.

4. Range of Versions (>= and <=)

   • Syntax: package_name>=1.0.0,<=2.0.0
   • Meaning: Installs a version within the specified range. Example: Flask>=1.1.0,<=2.0.1 includes versions between 1.1.0 and 2.0.1.
   • Best For: Ensuring some flexibility while staying within a compatible version range.

5. Exclude Specific Versions (!=)

   • Syntax: package_name!=1.0.1
   • Meaning: Excludes a particular version. Example: requests!=2.21.0 installs any version of requests except 2.21.0.
   • Best For: Avoiding known buggy or incompatible versions.

6. Compatible Release (~= or ^)

   • Syntax: package_name~=1.4 or package_name^1.4.0
   • Meaning: Installs versions up to, but not including, the next major version. Example: pandas~=1.2.3 includes versions like 1.2.4 but not 1.3.0.
   • Best For: Keeping compatibility within a minor version range.

7. Pre-release and Development Versions (<, >)

   • Syntax: package_name<2.0.0
   • Meaning: Allows installation of pre-release versions. Example: scipy<2.0.0 might include a development version like 1.5.0.dev.
   • Best For: Testing experimental versions, not typically used in production.

Example Usage in Requirements Files

Here are some example scenarios showing how to use these symbols:

• Single Requirement: flask==2.0.1 installs only version 2.0.1.
• Multiple Requirements: requests>=2.20.0,<3.0.0 installs versions from 2.20.0 up to, but not including, 3.0.0.
• Combined Exclusions: scipy>=1.5.2,!=1.6.0,!=1.7.1 installs from 1.5.2 onwards but excludes 1.6.0 and 1.7.1.

Best Practices

1. Avoid Exact Versioning (==) in Libraries: Using == restricts flexibility for future projects, so avoid it in libraries that might be used elsewhere.

2. Use Compatible Release (~=) in Production: This symbol allows updates while maintaining compatibility.

3. Test Development Versions Carefully: Isolate pre-release versions in a separate virtual environment for testing purposes.

4. Regularly Update Dependencies: Keeping dependencies up to date helps with security and performance. Use pip commands to check for updates.

References

1. Semantic versioning
2. Semantic versioning tool
3. https://elliott-king.github.io/2020/08/package_json_symbols/

Conclusion

Understanding Python dependency versioning symbols can be the difference between a stable environment and one filled with compatibility issues. Following these guidelines will help you create reliable, well-maintained Python environments.