Working With Ansible As A Noob: Troubleshooting Installation on MacOS

Working With Ansible As A Noob: Troubleshooting Installation on MacOS
Play this article

As part of my Udacity studies, I got introduced to Ansible. This is my first time working with any configuration management tool and of course, I had to go through the installation and setup process.

If you are new here, I am on a 3-month journey into the world of Cloud and DevOps Engineering, thanks to the ALX-T scholarship! You can check out the series that documents my progress.

Currently working on Enabling Continuous Delivery with deployment pipelines, using configuration management tools.

A lot of the concepts I encounter during the program are completely new to me, so it always takes more time to debug and fix issues that come up.

In this case, I had trouble properly installing Ansible on a MacOS but after several articles, I found a couple of commands and tips that made it easy to resolve those issues.

In this article, I'll be sharing two possible errors/issues you might encounter when installing Ansible as a beginner, and the solutions that could help.

The same way they helped me!

1) Unable to Install Ansible - Read Time out error

If you're trying to install Ansible with the recommended commands in the docs, and you get a couple of errors some minutes after:

  • Check if the errors has a ReadTimeoutError or Read timed out somewhere.

At first, I thought it was a problem with my connection (technically, it was or maybe it was not). I was able to get past it by increasing the default socket timeout.


  • Run your installation with an increased socket timeout
python3 -m pip install --default-timeout=1000 --user ansible

The increase worked for me, you can go higher if you have a worse connection or you still get the error.

2) Running ansible --version returns a command not found: ansible

This most likely happens if you got some warnings after successfully installing Ansible. In my case, the Ansible packages were installed in a directory that was not added to $PATH.

I wish I had taken screenshots of these errors though😬.

Again, I did some research to get an understanding of what was going on, and what needed to be done.


  • First, I confirmed that Ansible was indeed installed:
python3 -m pip show ansible
  • If the terminal you used for the installation is still open, you can copy the directory that needs to be added to path from there. If not, you can use these commands to locate it:
cd ~
find . | grep ansible

The second command returns a looonnngg list of paths, so you should use the CMD + F shortcut to search and locate /ansible.

  • Confirm you are in your root user directory (navigate there, if you are not), and list its contents to locate the .zshrc file
cd ~ && ls -a
  • You can check out the current contents of the file before proceeding to edit it
cat .zshrc
  • Invoke a command line editor (nano is fine)
nano .zshrc
  • Add the path
export PATH="/Users/user/Library/Python/3.8/bin:$PATH"

Remember the directory we searched for earlier? /Users/user/Library/Python/3.8/ was the full path for mine, yours may be different so ensure you are adding the correct path.

  • Save with Control + X, enter Y for Yes to modify the contents of the file.
  • Confirm your file now has the path
cat .zshrc
  • Run ansible --version again and it should work now✅.

This StackOverflow answer was extremely helpful in figuring things out.

These were the main issues I encountered during my installation. If you happen to encounter others, kindly share the issue and if/how you were able to resolve it.

That way, more beginners like me canspend less time troubleshooting when they come across articles like this one.

Thanks for reading, and I hope you found it useful somehow!


I encountered several other issues while trying to run different Ansible + CircleCI exercises for the course, and it was no easy feat resolving them.

Still, I am glad I am able to get a decent understanding of the concepts.

Khairah Signature.gif