script – Runs a local script on a remote node after transferring it — Ansible Documentation

- AnsibleFest
- Products
- Community
- Webinars & Training
- Blog

Documentation

# script – Runs a local script on a remote node after transferring it

- Synopsis
- Parameters
- Notes
- See Also
- Examples
- Status

## Synopsis

- The `script` module takes the script name followed by a list of space-delimited arguments.
- Either a free form command or `cmd` parameter is required, see the examples.
- The local script at path will be transferred to the remote node and then executed.
- The given script will be processed through the shell environment on the remote node.
- This module does not require python on the remote system, much like the raw module.
- This module is also supported for Windows targets.

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
chdir - added in 2.4 |  | Change into this directory on the remote node before running the script.
cmd string |  | Path to the local script to run followed by optional arguments.
creates - |  | A filename on the remote node, when it already exists, this step will not be run.
decrypt boolean added in 2.4 | Choices: no yes ← | This option controls the autodecryption of source files using vault.
executable - added in 2.6 |  | Name or path of a executable to invoke the script with.
free_form - |  | Path to the local script file followed by optional arguments.
removes - |  | A filename on the remote node, when it does not exist, this step will not be run.

## Notes

Note

- It is usually preferable to write Ansible modules rather than pushing scripts. Convert your script to an Ansible module for bonus points!
- The `ssh` connection plugin will force pseudo-tty allocation via `-tt` when scripts are executed. Pseudo-ttys do not have a stderr channel and all stderr is sent to stdout. If you depend on separated stdout and stderr result keys, please switch to a copy+command set of tasks instead of using script.
- If the path to the local script contains spaces, it needs to be quoted.
- This module is also supported for Windows targets.

## See Also

See also

shell – Execute shell commands on targets
  The official documentation on the shell module.
win_shell – Execute shell commands on target hosts
  The official documentation on the win_shell module.

## Examples

    - name: Run a script with arguments (free form)
      script: /some/local/script.sh --some-argument 1234

    - name: Run a script with arguments (using 'cmd' parameter)
      script:
        cmd: /some/local/script.sh --some-argument 1234

    - name: Run a script only if file.txt does not exist on the remote node
      script: /some/local/create_file.sh --some-argument 1234
      args:
        creates: /the/created/file.txt

    - name: Run a script only if file.txt exists on the remote node
      script: /some/local/remove_file.sh --some-argument 1234
      args:
        removes: /the/removed/file.txt

    - name: Run a script using an executable in a non-system path
      script: /some/local/script
      args:
        executable: /some/remote/executable

    - name: Run a script using an executable in a system path
      script: /some/local/script.py
      args:
        executable: python3

## Status

- This module is guaranteed to have backward compatible interface changes going forward. [stableinterface]
- This module is maintained by the Ansible Core Team. [core]

### Red Hat Support

More information about Red Hat’s support of this module is available from this Red Hat Knowledge Base article.

### Authors

- Ansible Core Team
- Michael DeHaan

Hint

If you notice any issues in this documentation, you can edit this document to improve it.