Dependency management issue: hard-pinned dependencies limit library usability

[sagostinho-nvidia]

Hello

I'd like to report a usability issue related to how the project specifies its dependencies in pyproject.toml + requirements.txt.

Problem:

The library hard-pins exact versions for all its dependencies (e.g., opencv-python==4.10.0.84, numpy==1.26.4, etc.). This makes it very difficult to integrate the library into a broader Python project that has other dependencies requiring more flexibility in versions, and produce a compatible python environment, via tools like uv, Poetry or pip-compile.

This practice treats abstract requirements (version ranges that describe API/behavior compatibility) as if they were concrete requirements (exact versions needed to reproduce an environment). The former is appropriate for libraries; the latter is appropriate for applications. For more discussion on the matter see https://packaging.python.org/en/latest/discussions/install-requires-vs-requirements/

Why this matters:

Hard-pinning dependencies in a library leads to:

• Dependency conflicts for downstream users
• Inflexibility in environments with shared or layered dependencies
• Increased maintenance burden for users who must override or manually patch requirements

Expected behavior:

Library dependencies should be declared using version ranges (e.g., requests>=2.25.0,<3.0.0), not exact pins. Exact pins, if needed, should be used in lockfiles (e.g., requirements.txt) for development or CI environments, not in the installable package metadata. These concepts are conflated in this project when in general they should be kept separate.

Suggested fix:

• Update [project.dependencies] to use appropriate version ranges.
• Retain hard pins only in dev/testing lockfiles (in this caserequirements.txt) as needed.

This would greatly improve compatibility and usability for anyone integrating the library into larger projects.

Thank you.

[pjannaty]

@codeJRV @zhe-thoughts to opine.

[codeJRV]

Thank you @sagostinho-nvidia your thoughtful feedback and for highlighting the challenges that hard-pinned dependencies can introduce for downstream users integrating this library into larger projects.

The reason dependencies in this repository are pinned to exact versions is that Cosmos intended to faithfully reproduce the work in the Cosmos research paper, and does not currently have the same scale of infrastructure needed to test all possible combinations of user-install environments ( think CUDA versions, PyTorch versions etc) like larger general-purpose reusable libraries such as like PyTorch or Numpy.

In research contexts, reproducibility is paramount: by specifying exact versions, we ensure that anyone running the code—now or in the future—can recreate the precise environment used to generate the published results. This is especially important when reviewers or other researchers revisit the project months later, as it guarantees that the code will behave exactly as it did during the original experiments.

“When you pin a dependency (for example by saying ‘numpy==1.1.3’) you explicitly point to a version of a library that a) you know works with your script b) was used to generate the result you present in your paper. This is very useful for people trying to replicate your results using your code as well as yourself attempting to revisit a project that was put aside for a while.”

That said, we recognize that this approach can make integration into broader ecosystems more difficult. The intent, therefore is not to force users to always use these exact versions, but to provide a baseline for reproducibility.

If you are deploying cosmos as part of a larger system or need to resolve dependency conflicts, you are absolutely encouraged to adjust the dependency versions as needed for your environment. The pinned requirements are there to guarantee a “known good” setup for reproducing published results, but they are not a technical barrier—feel free to modify them to suit your use case.

In other words, the strict pins are for reproducibility in the AI research context, but users are free (and encouraged) to adapt the dependencies as needed for their own deployments.

[sagostinho-nvidia]

Thank you for the detailed reply. I understand the emphasis on reproducibility in a research context. That said, I’d like to offer a few suggestions that I believe preserve reproducibility while improving usability for others who might want to adopt Cosmos in broader environments, without increasing the burden of maintainability.

(1) reproducibility via requirements.txt.

Given that reproducibility is the primary goal, requirements.txt is the standard way to achieve this. It’s designed to specify concrete dependencies for locked environments. So, as long as requirements.txt exists and is actively maintained to match the original research environment, that reproducibility goal is entirely met.

This would require explicitly guiding users to run

pip install -r requirements.txt

prior to installing the cosmos library. This keeps the focus on exact reproducibility where it matters, while not making it the default for users trying to import the library elsewhere.

Furthermore, since the library isn’t positioned as a general-purpose, production-ready tool, it might be worth to either:

(2a) Lifting version pins in pyproject.toml (e.g., don't specify version ranges at all), which keeps it flexible for downstream use. If cosmos is positioning itself as research only, it's acceptable to state to that compatibility outside the locked environment was not tested, but left open to facilitate integration.

(2b) Or removing project.dependencies entirely, signaling that requirements.txt is the authoritative source for the reproducible environment, and avoiding locking users into a specific dependency graph at install time.

[sophiahhuang]

Thanks for the details.

[sagostinho-nvidia]

Hello @sophiahhuang. I believe the issue was incorrectly closed as completed.

1. There was neither a change in the code addressing the suggestions I made.
2. There was also no follow-up discussion to my last reply suggestions.

[pjannaty]

Hello @sophiahhuang. I believe the issue was incorrectly closed as completed.

1. There was neither a change in the code addressing the suggestions I made.
2. There was also no follow-up discussion to my last reply suggestions.

@sagostinho-nvidia @codeJRV you both raise valid points. Can we relax dependency requirements by setting a lower bound?
@sagostinho-nvidia will you be able to take that on and test a few examples?

[sagostinho-nvidia]

Can we relax dependency requirements by setting a lower bound?

Yes. One can be more conservative or more aggressive in setting those lower bounds, assuming there's not a concrete known minimum version the project actually supports.

1. If one is aggressive and sets a lower bound lower than the actual minimum supported version, expect bug reports indicating the version was set is too low. The end user still won't be blocked because they can further raise lower bound up on their side, in their projects own dependencies / environment lock.
2. If one is conservative, less chances of bug reports, but one might be overlooking dependency versions that are actually supported.

I usually start by following semantic version guidelines: if packages have major versions, hopefully there's support for the entire major version. If they're still on minor versions, then it's a bit more risky to move out of the minor version that is reported in the locked environment.

@sagostinho-nvidia will you be able to take that on and test a few examples?

Not immediately, but once I start integrating cosmos with the project I'm working on, then yes.

I just opened this issue now to raise awareness to the problem, and to assess if down the line I contributed some changes loosening the dependency versions, these would not clash with the desires of the maintenance team.

[pvrraju]

Hey @pjannaty , @sagostinho-nvidia , @codeJRV ,

Thanks for talking about this. I decided to try the suggested solution.
I just opened a Pull Request that balances reproducibility with easy integration.
Here’s what changed:
pyproject.toml now uses flexible, minimum dependencies so it won’t break in larger projects.
requirements.txt still pins exact versions so anyone can recreate the research setup.
README.md and INSTALL.md now explain both options clearly, so users can pick the one they need.

PR : #124