Updated: 9 November 2026 · Applies to: Debian 13 (OpenSSH 10.0, bash 5.2), AlmaLinux 9 (bash 5.1), Ubuntu and Windows 10 and 11 OpenSSH client

ssh server myalias fails with command not found because a command sent over SSH runs in a non-interactive shell, and bash does not expand aliases there. The quick fix is to start an interactive shell for that one command: ssh server 'bash -ic myalias'. The cleaner fix is to turn the alias into a small script. This article covers both, and also the other kind of "SSH alias": a short name for the server itself in ~/.ssh/config.

Why the alias is not found

On the server, the user alice has this line in ~/.bashrc:

alias dfh='df -h /'

It works after logging in, but not as a remote command:

ssh web1 dfh

Output from our Debian 13 test (exit code 127):

bash: line 1: dfh: command not found

There are two reasons, and both matter:

  • Debian and Ubuntu start ~/.bashrc with a check that stops reading the file in a non-interactive shell:
    # If not running interactively, don't do anything
    case $- in
        *i*) ;;
          *) return;;
    esac
    So aliases and functions defined below that check never load for ssh server command.
  • Even when the alias is loaded (AlmaLinux and Rocky Linux have no such check in ~/.bashrc), the bash manual says aliases are not expanded in a non-interactive shell unless the expand_aliases option is set. In our AlmaLinux 9 test, sourcing ~/.bashrc in a non-interactive shell still gave dfh: command not found, while a shell function from the same file worked.

Fix 1: run an interactive shell for the command

ssh web1 'bash -ic dfh'

Output:

Filesystem      Size  Used Avail Use% Mounted on
overlay          48G   32G   14G  70% /

-i makes bash interactive, so it reads ~/.bashrc and expands aliases. Without a terminal, bash may also print cannot set terminal process group and no job control in this shell. These warnings are harmless. For full-screen commands such as top or htop, add -t so ssh allocates a terminal: ssh -t web1 'bash -ic top'.

The same works for functions in ~/.bashrc, with arguments:

ssh web1 "bash -ic 'diskuse /var/log'"

Fix 2: load a separate alias file with expand_aliases

Debian and Ubuntu load ~/.bash_aliases from ~/.bashrc if it exists, so you can keep your aliases there and load that file directly. The alias must be used on a new line after it is defined, because bash reads a whole line before expanding aliases:

ssh web1 'shopt -s expand_aliases
. ~/.bash_aliases
dfh'

This worked in our Debian 13 test. The same commands on one line separated by ; failed with dfh: command not found.

Fix 3 (recommended): turn the alias into a script

A script works in every shell, from cron, and over SSH, with no tricks. On the server:

mkdir -p ~/bin
printf '#!/bin/sh\ndf -h /\n' > ~/bin/dfh
chmod +x ~/bin/dfh

One catch: on Debian and Ubuntu, ~/bin is added to PATH in ~/.profile, which a plain SSH command does not read. In our test, ssh web1 dfh still failed and PATH was only /usr/local/bin:/usr/bin:/bin:/usr/games. Either call the script with its full path:

ssh web1 '~/bin/dfh'

or add this as the first line of ~/.bashrc on the server, before the "not running interactively" check:

export PATH="$HOME/bin:$PATH"

After that, ssh web1 dfh worked. On AlmaLinux and Rocky Linux, the default ~/.bashrc already adds $HOME/bin and $HOME/.local/bin to PATH. Another option is a login shell, which reads ~/.profile: ssh web1 'bash -lc dfh' also worked.

An alias for the server: ~/.ssh/config

Many people searching for "ssh alias" want the opposite: a short name on their own computer, so ssh web1 replaces ssh -p 2222 alice@203.0.113.10. Add a Host block to ~/.ssh/config on your computer:

Host web1
    HostName 203.0.113.10
    User alice
    Port 2222
    IdentityFile ~/.ssh/id_ed25519

Protect the file with chmod 600 ~/.ssh/config. Now ssh web1, scp file web1: and rsync all use those settings. To see what ssh will actually use for a host:

ssh -G web1 | grep -E '^(hostname|user|port|identityfile) '

Output:

user alice
hostname 203.0.113.10
port 2222
identityfile ~/.ssh/id_ed25519

A bash alias on your computer does the same job for a single server: add alias web1='ssh -p 2222 alice@203.0.113.10' to your local ~/.bashrc. The config file is better, because scp, sftp and rsync understand it too. For more on custom ports, see How to Connect to SSH on a Different Port.

SSH alias on Windows

Windows 10 (build 1809 and later) and Windows 11 include the OpenSSH client. According to Microsoft, it reads your personal settings from %userprofile%\.ssh\config (for example C:\Users\alice\.ssh\config), so the same Host web1 block works there and ssh web1 works in PowerShell and Command Prompt. Create the file in Notepad and save it without a .txt extension. To create a key on Windows, see How to Create SSH Keys on Windows and Log In to a Linux Server.

SSH alias with a password

The ssh config file has no password setting on purpose. Use an SSH key instead: it is safer and makes ssh web1 log in without a prompt. See How to set up SSH keys for authentication.

If a server really only allows passwords, the sshpass tool can supply one from a file that only you can read (sshpass 1.10 in our test):

sshpass -f ~/.ssh/web1.pass ssh web1 hostname

A wrong password made it exit with code 5 after Permission denied, please try again. Avoid sshpass -p password, because the password then shows in your shell history and the process list.

Related: How to Create and Use Alias Command in Linux and Understanding Bash Startup Files: Profile and Bashrc on Linux.

Official documentation: GNU Bash manual, ssh_config manual, OpenSSH configuration on Windows (Microsoft).

Related services

KVM VPS hosting

NVMe SSD and full root access, with Free Basic Managed Support.

Unmanaged dedicated servers

full root access and free IPMI KVM, with Free Basic Managed Support.

Managed dedicated servers

our engineers look after the server for you, from $135 a month.

Was this answer helpful?

Still stuck? Open a ticket