diff --git a/news/6a054cec-e4d6-4494-a554-90a2c0bee837.trivial b/news/6a054cec-e4d6-4494-a554-90a2c0bee837.trivial new file mode 100644 index 00000000000..e69de29bb2d diff --git a/src/pip/_internal/main.py b/src/pip/_internal/main.py index 1e922402a0b..855569f3101 100644 --- a/src/pip/_internal/main.py +++ b/src/pip/_internal/main.py @@ -19,6 +19,32 @@ logger = logging.getLogger(__name__) +# Do not import and use main() directly! Using it directly is actively +# discouraged by pip's maintainers. The name, location and behavior of +# this function is subject to change, so calling it directly is not +# portable across different pip versions. + +# In addition, running pip in-process is unsupported and unsafe. This is +# elaborated in detail at +# https://pip.pypa.io/en/stable/user_guide/#using-pip-from-your-program. +# That document also provides suggestions that should work for nearly +# all users that are considering importing and using main() directly. + +# However, we know that certain users will still want to invoke pip +# in-process. If you understand and accept the implications of using pip +# in an unsupported manner, the best approach is to use runpy to avoid +# depending on the exact location of this entry point. + +# The following example shows how to use runpy to invoke pip in that +# case: +# +# sys.argv = ["pip", your, args, here] +# runpy.run_module("pip", run_name="__main__") +# +# Note that this will exit the process after running, unlike a direct +# call to main. As it is not safe to do any processing after calling +# main, this should not be an issue in practice. + def main(args=None): if args is None: args = sys.argv[1:]