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
~/.bashrcwith a check that stops reading the file in a non-interactive shell:# If not running interactively, don't do anything case $- in *i*) ;; *) return;; esacSo aliases and functions defined below that check never load forssh 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 theexpand_aliasesoption is set. In our AlmaLinux 9 test, sourcing~/.bashrcin a non-interactive shell still gavedfh: 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).