Incompatibility of new pvlib with solarfactors run_timeseries_engine

[sophie-pelland]

Describe the bug
We had code that was working with pvlib 0.13.1 that used run_timeseries_engine. It fails with pvlib 0.15.0.

The error mentions the code cannot find components["horizon"]. After looking at the inner workings of the code, solarfactors calls on irradiance.perez. And the output of this has been changed such that a "poa_" prefix has been added, i.e. "horizon" has become "poa_horizon". I believe this is the source of the error.

[markcampanelli]

This was listed as an expected breaking change in the v0.14.0 release on 16 Jan 2026. https://pvlib-python.readthedocs.io/en/stable/whatsnew.html

[markcampanelli]

So, despite multiple ongoing breakage examples such as this one, IRL, I will probably never win this argument: solarfactors could better protect against such breakages by putting a hard upper bound on its dependency on (a pre-v1.0 version of) pvlib-python:

https://github.com/pvlib/solarfactors/blob/ecbfc863657e239817603a43898ae173c7ccad9c/pyproject.toml#L29

[sophie-pelland]

Thanks for the info, Mark. On our end, for now we reverted to pvlib 0.13.1, but obviously that is not a great solution.

[markcampanelli]

The history of pvfactors/solarfactors appears to have complicated this matter as well. Now there appears to be a circular dependency in which pvlib imports solarfactors and vice versa, essentially leading to the need for coupled releases of supposedly "independent" repos to prevent the problem you hit. As a quickish fix, I think a change needs to be made in pvfactors that keys those irradiance fields differently depending on the detected version of pvlib. A better, longer term solution should perhaps try to engineer away this circular dependency.

[sophie-pelland]

One of my colleagues imported pvfactors (rather than solarfactors), and she reports that the bug does not occur with the latest pvlib version in that case.

[echedey-ls]

You just need to update both dependencies as long as you want to use pvlib>=0.14.
pip install --upgrade pvlib solarfactors

Source: https://solarfactors.readthedocs.io/en/latest/whatsnew.html#v1-6-1-january-15-2026

If you encounter further problems, please report back with the exact version of the two dependencies (pip list | grep "pvlib\|solarfactors" if you are on Linux). I'll close this issue as this should fix your problem.

[markcampanelli]

(@echedey-ls beat me to it!)

@sophie-pelland It looks like someone indeed tried to head off this problem in pvlib/solarfactors#39.

Did you try pip install -U solarfactors, in order to ensure that you are using solarfactors v1.6.1? (You can use pip list to verify your versions.)

If all else fails, try installing the latest pvlib-python with the solarfactors option in a fresh virtual environment.

It appears that when you upgraded pvlib-python, pip was none the wiser that it needed to upgrade solarfactors along with it, due to the dependency-specification issues I outlined above. I stand by my claim that this pain can be better avoided by better specifying to pip what it should be doing.

[sophie-pelland]

Upgrading both pvlib and solarfactors worked for me. Thanks @echedey-ls and @markcampanelli ! I should have thought of that!

[kandersolar]

@sophie-pelland glad your issue got sorted!

solarfactors could better protect against such breakages by putting a hard upper bound on its dependency on (a pre-v1.0 version of) pvlib-python

Mark, I think I have explained previously that we cannot start using upper bounds to solve this kind of problem. Example:

• The current solarfactors release has no restrictions on the pvlib requirement. Ok, so we make a new solarfactors release to require pvlib<0.16.
• Later, we release pvlib==0.16.0.
• A user with the latest solarfactors wants to upgrade to the latest pvlib and runs pip install pvlib==0.16.0.

What happens? pip would try to install the latest pvlib and notice that the existing solarfactors installation is marked as not compatible. Does it emit an error and abort the installation? No, it would proceed to downgrade solarfactors to the previous release, since that one declares no issue with the demanded pvlib version. Problem solved! Except not really.

Regardless of the arguments for and against upper bounds in general, the fact that we have not specified upper bounds since the first release means that starting now just will not work.

[markcampanelli]

@kandersolar The accepted solution here was pip install --upgrade pvlib solarfactors.

AFAICT, testing this with pip 26.0.1 on my own solarfactors tag on a fork (but not from PyPI) with "pvlib>=0.9.0,<0.14" specified in in the pyproject.toml, solarfactors will NOT be downgraded when using the above command (likely due to the --upgrade flag). Nor will pvlib be upgraded, but that is by choice/design, in order to not break someone's existing, happy code. (An even better test would be to put this up on PyPI test server with additional versions for pip to choose from to fully replicate the change to using hard upper limits.)

I don't think hard upper limits are incompatible with a more careful use of pip that is required when using pvlib together with solarfactors. I hold the view that the bigger problem is the circular dependency, not the hard upper limits, and what is lost for production build environments here is the bigger issue. The fact that pip could be seen as requiring the --upgrade to avoid a downgrade IS annoying, but that is also NOT a design choice that is under pvlib's control, whereas the semantic-versioning based upper limits are.