a08459a814
* Update the documentation to list Python 3 as official
* Add some reference targets for inventory variables so we can link to docs
* Add a platform FAQ section
Populate it with
* virtualenv info (previously on the python3 support page)
* BSD (Link to the working with BSD page)
* Solaris (Document how to work around the non-POSIX shell on some
Solaris hosts)
Fixes #21594
* Fix some refs in the release_and_maintenance document
* Fix unindent error in module template
Fix for the module/plugin template unintentionally unindented inside of
a raw block, leading to errors like:
ERROR: docs/docsite/rst/modules/redshift_facts_module.rst:289:0: Explicit markup ends without a blank line; unexpected unindent.
* Make wording for Solaris troubleshooting better.
92 lines
3.7 KiB
ReStructuredText
92 lines
3.7 KiB
ReStructuredText
================
|
|
Python 3 Support
|
|
================
|
|
|
|
Ansible 2.5 and above have support for Python 3. Previous to 2.5, the Python 3 support was
|
|
considered a tech preview. This topic discusses how to setup your controller and managed machines
|
|
to use Python 3.
|
|
|
|
.. note:: Ansible supports Python version 3.5 and above only.
|
|
|
|
On the controller side
|
|
----------------------
|
|
|
|
The easiest way to run :command:`/usr/bin/ansible` under Python 3 is to install it with the Python3
|
|
version of pip. This will make the default :command:`/usr/bin/ansible` run with Python3:
|
|
|
|
.. code-block:: shell
|
|
|
|
$ pip3 install ansible
|
|
$ ansible --version | grep "python version"
|
|
python version = 3.6.2 (default, Sep 22 2017, 08:28:09) [GCC 7.2.1 20170915 (Red Hat 7.2.1-2)]
|
|
|
|
If you are running Ansible :ref:`from_source` and want to use Python 3 with your source checkout, run your
|
|
command via ``python3``. For example:
|
|
|
|
.. code-block:: shell
|
|
|
|
$ source ./hacking/env-setup
|
|
$ python3 $(which ansible) localhost -m ping
|
|
$ python3 $(which ansible-playbook) sample-playbook.yml
|
|
|
|
.. note:: Individual Linux distribution packages may be packaged for Python2 or Python3. When running from
|
|
distro packages you'll only be able to use Ansible with the Python version for which it was
|
|
installed. Sometimes distros will provide a means of installing for several Python versions
|
|
(via a separate package or via some commands that are run after install). You'll need to check
|
|
with your distro to see if that applies in your case.
|
|
|
|
|
|
Using Python 3 on the managed machines with commands and playbooks
|
|
------------------------------------------------------------------
|
|
|
|
* Set the ``ansible_python_interpreter`` configuration option to :command:`/usr/bin/python3`. The
|
|
``ansible_python_interpreter`` configuration option is usually set as an inventory
|
|
variable associated with a host or group of hosts:
|
|
|
|
.. code-block:: ini
|
|
|
|
# Example inventory that makes an alias for localhost that uses Python3
|
|
localhost-py3 ansible_host=localhost ansible_connection=local ansible_python_interpreter=/usr/bin/python3
|
|
|
|
# Example of setting a group of hosts to use Python3
|
|
[py3-hosts]
|
|
ubuntu16
|
|
fedora27
|
|
|
|
[py3-hosts:vars]
|
|
ansible_python_interpreter=/usr/bin/python3
|
|
|
|
.. seealso:: :ref:`intro_inventory` for more information.
|
|
|
|
* Run your command or playbook:
|
|
|
|
.. code-block:: shell
|
|
|
|
$ ansible localhost-py3 -m ping
|
|
$ ansible-playbook sample-playbook.yml
|
|
|
|
|
|
Note that you can also use the `-e` command line option to manually
|
|
set the python interpreter when you run a command. This can be useful if you want to test whether
|
|
a specific module or playbook has any bugs under Python 3. For example:
|
|
|
|
.. code-block:: shell
|
|
|
|
$ ansible localhost -m ping -e 'ansible_python_interpreter=/usr/bin/python3'
|
|
$ ansible-playbook sample-playbook.yml -e 'ansible_python_interpreter=/usr/bin/python3'
|
|
|
|
What to do if an incompatibility is found
|
|
-----------------------------------------
|
|
|
|
We have spent several releases squashing bugs and adding new tests so that Ansible's core feature
|
|
set runs under both Python 2 and Python 3. However, bugs may still exist in edge cases and many of
|
|
the modules shipped with Ansible are maintained by the community and not all of those may be ported
|
|
yet.
|
|
|
|
If you find a bug running under Python 3 you can submit a bug report on `Ansible's GitHub project
|
|
<https://github.com/ansible/ansible/issues/>`_. Be sure to mention Python3 in the bug report so
|
|
that the right people look at it.
|
|
|
|
If you would like to fix the code and submit a pull request on github, you can
|
|
refer to :ref:`developing_python3` for information on how we fix
|
|
common Python3 compatibility issues in the Ansible codebase.
|