Getting a REPL or Interactive Shell

rules_python provides a REPL to help with debugging and developing. The goal of the REPL is to present an environment identical to what a py_binary creates for your code.

Usage

Start the REPL with the following command:

$ bazel run @rules_python//python/bin:repl
Python 3.11.11 (main, Mar 17 2025, 21:02:09) [Clang 20.1.0 ] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>

Settings like //python/config_settings:python_version will influence the exact behaviour.

$ bazel run @rules_python//python/bin:repl --@rules_python//python/config_settings:python_version=3.13
Python 3.13.2 (main, Mar 17 2025, 21:02:54) [Clang 20.1.0 ] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>

See //python/config_settings and Environment Variables for more settings.

Importing Python targets

The //python/bin:repl_dep command line flag gives the REPL access to a target that provides the PyInfo provider.

$ bazel run @rules_python//python/bin:repl --@rules_python//python/bin:repl_dep=@rules_python//tools:wheelmaker
Python 3.11.11 (main, Mar 17 2025, 21:02:09) [Clang 20.1.0 ] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import tools.wheelmaker
>>>

Customizing the shell

By default, the //python/bin:repl target will invoke the shell from the code module. It’s possible to switch to another shell by writing a custom “stub” and pointing the target at the necessary dependencies.

IPython Example

For an IPython shell, create a file as follows.

import IPython
IPython.start_ipython()

Assuming the file is called ipython_stub.py and the pip.parse hub’s name is my_deps, set this up in the .bazelrc file:

# Allow the REPL stub to import ipython. In this case, @my_deps is the hub name
# of the pip.parse() call.
build --@rules_python//python/bin:repl_stub_dep=@my_deps//ipython

# Point the REPL at the stub created above.
build --@rules_python//python/bin:repl_stub=//path/to:ipython_stub.py