diff --git a/doc/python_bindings.rst b/doc/python_bindings.rst index 456677d5ec31..1716f190b6e9 100644 --- a/doc/python_bindings.rst +++ b/doc/python_bindings.rst @@ -13,6 +13,9 @@ installed as a single package called ``pydrake``. .. _python-bindings-binary: +Installation +============ + Binary Installation for Python ------------------------------ @@ -46,6 +49,43 @@ macOS, pay special attention to :ref:`this note `. Python 2.7 is currently the only supported version for the bindings supplied by the binary packages. To use Python 3.x, see below for building from source. +Inside ``virtualenv`` +^^^^^^^^^^^^^^^^^^^^^ + +At present, Drake is not installable via ``pip``. However, you can still +incorporate its install tree into a ``virtualenv`` +`FHS `_-like +environment. + +An example for ``python2``, where you should replace ```` and +````: + +.. code-block:: shell + + # Setup drake, and run prerequisites. + curl -o drake.tar.gz https://drake-packages.csail.mit.edu/drake/nightly/drake-latest-.tar.gz + mkdir -p + tar -xvzf drake.tar.gz -C --strip-components=1 + # - You may need `sudo` here. + /share/drake/setup/install_prereqs + + # Setup a virtualenv over the drake install. + python2 -m virtualenv -p python2 --system-site-packages + +.. note:: + + You can extract Drake into an existing ``virtualenv`` tree if you have + already run ``install_prereqs``; however, you should ensure that you have + run ``install_prereqs``. Before you do this, you should capture / freeze + your current requirements to reproduce your environment if there are + conflicts. + +To check if this worked, follow the instructions as +:ref:`shown below `, but either: + +* Use ``/bin/python`` instead of ``python``, or +* Source ``/bin/activate`` in your current shell session. + Building the Python Bindings ---------------------------- @@ -87,10 +127,13 @@ As an example, continuing from the code snippets from above: .. _using-python-bindings: Using the Python Bindings -------------------------- +========================= + +Check Installation +------------------ -To use the Drake Python bindings, follow the steps above to install or build -Drake. To check this: +After following the above install steps, check to ensure you can import +``pydrake``: .. code-block:: shell @@ -193,7 +236,7 @@ explicitly refer to each symbol: simulator = pydrake.systems.analysis.Simulator(diagram) Differences with C++ API -======================== +------------------------ In general, the `Python API `_ should be close to the `C++ API `_. There are some exceptions: diff --git a/setup/mac/binary_distribution/requirements.txt b/setup/mac/binary_distribution/requirements.txt index 78a6e8702593..03e18f02b5bb 100644 --- a/setup/mac/binary_distribution/requirements.txt +++ b/setup/mac/binary_distribution/requirements.txt @@ -6,3 +6,4 @@ pyzmq six tornado u-msgpack-python +virtualenv diff --git a/setup/ubuntu/binary_distribution/packages-bionic.txt b/setup/ubuntu/binary_distribution/packages-bionic.txt index 7ea13d6c8f8e..dbc3ef269624 100644 --- a/setup/ubuntu/binary_distribution/packages-bionic.txt +++ b/setup/ubuntu/binary_distribution/packages-bionic.txt @@ -39,6 +39,7 @@ python-six python-tk python-tornado python-u-msgpack +python-virtualenv python-yaml python-zmq python3 @@ -50,6 +51,7 @@ python3-six python3-tk python3-tornado python3-u-msgpack +python3-virtualenv python3-yaml python3-zmq qtbase5-dev diff --git a/setup/ubuntu/binary_distribution/packages-xenial.txt b/setup/ubuntu/binary_distribution/packages-xenial.txt index c5d606ea5143..0dbaf09bf1ec 100644 --- a/setup/ubuntu/binary_distribution/packages-xenial.txt +++ b/setup/ubuntu/binary_distribution/packages-xenial.txt @@ -38,6 +38,7 @@ python-scipy python-six python-tk python-tornado +python-virtualenv python-yaml python-zmq qtbase5-dev