Ansible Documentation: Complete Guide to Finding and Using Official Docs
By Luca Berton · Published 2024-01-01 · Category: installation
Navigate Ansible documentation effectively. Official docs, module reference, collection docs, ansible-doc CLI, playbook keywords, configuration reference.
Where to Find Ansible Documentation
Ansible documentation is spread across several locations. Here's the definitive map.
Official Documentation Sites
| Resource | URL | What's There |
|----------|-----|-------------|
| Ansible Core docs |
Most-Used Documentation Pages
Bookmark these — you'll use them constantly:
• Module Index — searchable list of every module
• Playbook Keywords — every keyword you can use in plays, roles, blocks, and tasks
• Special Variables — inventory_hostname, ansible_facts, hostvars, etc.
• Jinja2 Filters — data transformation in templates
• ansible.cfg Settings — every configuration option
• Connection Plugins — SSH, WinRM, network_cli, httpapi
See also: Learn Ansible: Complete Beginner to Advanced Roadmap (2026)
ansible-doc: Documentation From the Command Line
The ansible-doc command is the fastest way to check module documentation without opening a browser.
Look Up a Module
# Full documentation for a module
ansible-doc ansible.builtin.copy
# Short usage snippet
ansible-doc -s ansible.builtin.copy
# Output:
# - name: Copy files to remote locations
# copy:
# backup: # Create backup file with timestamp
# content: # Write content directly (mutually exclusive with src)
# dest: # (required) Remote absolute path
# ...
List All Modules
# List every available module
ansible-doc -l
# Filter by keyword
ansible-doc -l | grep -i "firewall"
# community.general.ufw
# ansible.posix.firewalld
# ...
# List modules in a specific collection
ansible-doc -l -t module ansible.builtin
ansible-doc -l -t module community.general
Other Plugin Types
# Lookup plugins
ansible-doc -t lookup file
ansible-doc -t lookup env
# Filter plugins
ansible-doc -t filter ansible.builtin.regex_replace
# Connection plugins
ansible-doc -t connection ansible.netcommon.network_cli
# Callback plugins
ansible-doc -t callback ansible.builtin.debug
# Inventory plugins
ansible-doc -t inventory ansible.builtin.yaml
# All plugin types
ansible-doc -t module # Modules (default)
ansible-doc -t lookup # Lookup plugins
ansible-doc -t filter # Filter plugins
ansible-doc -t callback # Callback plugins
ansible-doc -t connection # Connection plugins
ansible-doc -t inventory # Inventory plugins
ansible-doc -t become # Become plugins
ansible-doc -t strategy # Strategy plugins
ansible-doc -t vars # Vars plugins
ansible-doc -t cache # Cache plugins
JSON Output for Scripts
# Machine-readable documentation
ansible-doc ansible.builtin.copy --json
# Useful for building custom tooling or documentation sites
ansible-navigator doc (With EEs)
If you use Execution Environments, ansible-navigator doc shows documentation for modules inside the EE:
# Interactive TUI documentation browser
ansible-navigator doc ansible.builtin.copy
# Stdout mode
ansible-navigator doc ansible.builtin.copy -m stdout
# List all modules in the EE
ansible-navigator doc -l -m stdout
# Browse all collections in the EE
ansible-navigator collections
This is important because your local Ansible installation may have different collections than your EE. Always check documentation against the EE you'll run in production.
See also: Ansible 2.17.0-rc1: Elevating Automation with ‘Gallows Pole’
Reading Module Documentation
Every module doc page follows the same structure:
1. Synopsis
What the module does in one paragraph.2. Requirements
Python libraries or system packages needed on the target host (not the control node).3. Parameters
The most important section. Each parameter shows: • Name — the parameter name • Type — string, boolean, list, dict, int, path, etc. • Required — yes/no • Default — default value if not specified • Choices — valid values for restricted parameters • Description — what it does4. Notes
Edge cases, version requirements, and gotchas.5. Examples
Copy-paste-ready YAML. Start here when learning a new module.6. Return Values
What the module returns inregister — essential for when conditions and debug output.
Example: Reading the copy Module Doc
$ ansible-doc ansible.builtin.copyKey parameters to understand:
# Required
dest: # Remote absolute path (required)
# Content source (pick one)
src: # Local file path to copy
content: # Write this string directly to dest
# Options
mode: # File permissions (e.g., '0644')
owner: # File owner
group: # File group
backup: # Create backup before overwriting (yes/no)
validate: # Command to validate file before placing (e.g., 'visudo -cf %s')
remote_src: # If true, src is on remote host, not control node
force: # Replace even if dest exists and is identical (default: yes)
Collection Documentation
Find a Collection's Docs
# What collections are installed?
ansible-galaxy collection list
# Documentation for a specific collection
ansible-doc -l -t module amazon.aws
ansible-doc amazon.aws.ec2_instance
Install a Collection and Read Its Docs
# Install
ansible-galaxy collection install community.general
# Read
ansible-doc community.general.ufw
ansible-doc community.general.nmcli
ansible-doc community.general.timezone
Collection Documentation Sites
Most major collections maintain their own documentation sites:
| Collection | Documentation |
|-----------|--------------|
| ansible.builtin |
See also: Ansible Playbook: Write and Run Your First Playbook (Complete Guide)
Playbook Language Reference
Playbook Keywords
The playbook keywords reference lists every keyword by context:
Play-level keywords:
- name: Example play
hosts: webservers # Target hosts (required)
become: true # Privilege escalation
gather_facts: true # Collect system facts
serial: 3 # Rolling update batch size
max_fail_percentage: 10 # Fail play if >10% hosts fail
any_errors_fatal: true # Stop on first failure
strategy: free # Execution strategy
environment: # Environment variables
http_proxy: "http://proxy:3128"
vars: # Play variables
app_version: "2.0"
vars_files: # Load variables from files
- vars/production.yml
roles: # Include roles
- common
- webserver
pre_tasks: [] # Tasks before roles
tasks: [] # Main tasks
post_tasks: [] # Tasks after roles
handlers: [] # Triggered tasksTask-level keywords:
- name: Example task
ansible.builtin.copy:
src: file.conf
dest: /etc/app/file.conf
become: true # Escalate for this task
become_user: postgres # Escalate to specific user
when: ansible_os_family == "Debian" # Conditional
loop: "{{ packages }}" # Iterate
register: result # Capture output
changed_when: false # Override change detection
failed_when: result.rc > 1 # Override failure detection
ignore_errors: true # Continue on failure
no_log: true # Hide sensitive output
notify: restart service # Trigger handler
tags: [deploy, config] # Tags for selective runs
delegate_to: localhost # Run on different host
run_once: true # Execute only once
retries: 3 # Retry on failure
delay: 10 # Seconds between retries
until: result is success # Retry condition
timeout: 300 # Task timeout in seconds
async: 3600 # Run asynchronously
poll: 10 # Async polling intervalOffline Documentation
Build Local Docs
# Clone Ansible docs
git clone https://github.com/ansible/ansible-documentation.git
cd ansible-documentation/docs/docsite
# Build HTML docs
pip install -r requirements.txt
make webdocs
# Open in browser
open _build/html/index.html
ansible-doc Works Offline
ansible-doc reads documentation from installed module Python files — no internet required:
# Works completely offline
ansible-doc ansible.builtin.apt
ansible-doc -lGetting Help
| Channel | URL | Best For |
|---------|-----|----------|
| Ansible Forum | #ansible on Libera.Chat / Matrix | Real-time chat |
| Stack Overflow | [ansible] tag | Specific technical questions |
| Reddit | r/ansible | Community discussions |
| Ansible Bullhorn | Newsletter | Release notes, community news |
FAQ
Where is the official Ansible documentation?
The primary documentation site is
How do I check module documentation from the terminal?
Use ansible-doc . For example: ansible-doc ansible.builtin.copy. Use -s for a short snippet, -l to list all modules, and -t to specify plugin type (lookup, filter, callback, etc.).
How do I find which collection a module belongs to?
Every module has a fully qualified collection name (FQCN) like ansible.builtin.copy or community.general.ufw. The format is namespace.collection.module. Run ansible-doc -l | grep module_name to find it.
Can I use Ansible documentation offline?
Yes. ansible-doc works completely offline using the installed module files. For full HTML documentation, clone the ansible-documentation repository and build it locally with Sphinx.
How do I keep up with Ansible changes?
Subscribe to the Ansible Bullhorn newsletter for release announcements. Check the changelog for version-specific changes. Follow ansible-core releases on GitHub.
Conclusion
Ansible documentation lives at docs.ansible.com for the core engine and collection modules, and at docs.redhat.com for AAP enterprise features. The ansible-doc CLI gives you instant offline access to any module's parameters, examples, and return values. Start with the Examples section of any module doc — it's the fastest path from "what does this do?" to working automation.
Related Articles
• What is Ansible and How Does It Work? • Ansible Playbook Examples: Complete Beginner Guide • Ansible Roles: Complete Guide • AAP 2.6 ansible-navigator: Modern CLI for Automation Development • Ansible Collections: Install, Use, and Create Custom CollectionsCategory: installation