Guides

~/.bashrc explained: when bash reads it, what belongs in it and how to fix it

What ~/.bashrc is, when bash reads it (login, non-login and SSH shells), what belongs in it vs ~/.profile, how to reload it and how to fix a broken bashrc.

Published ~8 min read
On this page

Short answer: ~/.bashrc is a shell script in your home directory that bash runs every time it starts an interactive shell that is not a login shell, such as a new terminal tab or typing bash. On Debian and Ubuntu the default ~/.profile loads it for SSH logins as well, which is why it is the place for aliases, the prompt and history settings. After editing it, run source ~/.bashrc to apply it to the shell you are in.

bash
nano ~/.bashrc          # edit the file
bash -n ~/.bashrc       # check the syntax, runs nothing
source ~/.bashrc        # load it into the current shell (short form: . ~/.bashrc)

The startup rules below come from the bash manual (section INVOCATION in man bash). We checked each one with bash 5.2.15 on Debian 12, using a throwaway home directory from mktemp -d, so no real dotfiles were touched.

When bash reads ~/.bashrc, and when it does not

Bash sorts every new shell into two questions: is it interactive (you type at a prompt) and is it a login shell (the first shell of a session)? The answer decides the files:

ShellTypical exampleFiles bash reads
Interactive, not loginNew terminal window on a Linux desktop, typing bash/etc/bash.bashrc (Debian, Ubuntu), then ~/.bashrc
Interactive loginssh user@host, console login, bash -l, su -/etc/profile, then the first of ~/.bash_profile, ~/.bash_login, ~/.profile
Non-interactiveScripts, bash -c, cron jobsNone, only the file named in $BASH_ENV
Non-interactive, started by sshdssh user@host command~/.bashrc on Debian and Ubuntu builds (see below)
Invoked as sh#!/bin/sh scripts, sh -l/etc/profile and ~/.profile for login shells, $ENV for interactive ones

So a login shell never reads ~/.bashrc by itself. It only happens because the stock ~/.profile on Debian and Ubuntu contains . "$HOME/.bashrc" when it runs under bash. You can watch the order with two one-line files:

Test with a throwaway HOME · bash 5.2.15
H=$(mktemp -d)
echo 'echo "read ~/.bashrc"' > "$H/.bashrc"
printf '%s\n' 'echo "read ~/.profile"' '[ -f ~/.bashrc ] && . ~/.bashrc' > "$H/.profile"

$ HOME=$H bash -i -c true          # interactive
read ~/.bashrc
$ HOME=$H bash -l -c true          # login
read ~/.profile
read ~/.bashrc
$ HOME=$H bash -c true             # neither: no output

$ echo 'echo "read ~/.bash_profile"' > "$H/.bash_profile"
$ HOME=$H bash -l -c true
read ~/.bash_profile

The last test is the classic trap: once a ~/.bash_profile exists, bash stops reading ~/.profile, and with it your ~/.bashrc. The bash manual's answer is one line in ~/.bash_profile:

~/.bash_profile
if [ -f ~/.bashrc ]; then . ~/.bashrc; fi

On Debian and Ubuntu, /etc/bash.bashrc runs before ~/.bashrc because both distributions compile bash with the SYS_BASHRC option; upstream bash does not read that file. /etc/skel holds the default .bashrc, .profile and .bash_logout that useradd -m and adduser copy into every new home directory.

Why SSH sessions sometimes ignore ~/.bashrc

Aliases that work in a local terminal but not after ssh come down to three causes:

  • A ~/.bash_profile without the source line. An SSH login is a login shell, so the trap above applies. Add the line, or delete an empty ~/.bash_profile.
  • Your login shell is not bash. The last field of getent passwd $USER names it. On Debian 12, useradd -D reports SHELL=/bin/sh, so accounts made with plain useradd get /bin/sh, which never reads ~/.bashrc; chsh -s /bin/bash changes it.
  • A command over SSH stops at the guard. Debian and Ubuntu build bash with SSH_SOURCE_BASHRC (upstream leaves it off), so ssh host command does read ~/.bashrc. But the stock file starts with a check that returns at once when the shell is not interactive:
top of /etc/skel/.bashrc · Debian 12 and Ubuntu
# If not running interactively, don't do anything
case $- in
    *i*) ;;
      *) return;;
esac

We simulated an sshd start (the SSH_CLIENT variable set, a fresh shell level) with a copy of that file plus one echo line above and one below the guard. Only the line above it ran, and HISTSIZE, set further down, stayed empty. So anything a remote command needs, such as an export for ssh host make deploy, goes above the guard. The environment variable guide covers which file suits which variable.

What the default ~/.bashrc on Debian and Ubuntu does

Both distributions ship the file from the bash package as /etc/skel/.bashrc. In order, it:

  • returns early for non-interactive shells (the guard above);
  • sets HISTCONTROL=ignoreboth, so commands starting with a space and repeated lines stay out of history, turns on histappend so parallel sessions do not overwrite each other's history, and keeps HISTSIZE=1000 lines in memory and HISTFILESIZE=2000 in ~/.bash_history;
  • turns on checkwinsize, so output adapts after you resize the window;
  • builds PS1 as user@host:dir$, in colour only when TERM is xterm-color or ends in -256color, or when you uncomment force_color_prompt=yes;
  • sets the terminal title, adds alias ls='ls --color=auto';
  • loads ~/.bash_aliases if it exists, and bash completion from /usr/share/bash-completion/bash_completion.

Ubuntu's copy (the same in 24.04 and 26.04) differs in a few lines: it enables lesspipe, the grep --color=auto aliases, ll='ls -alF', la, l and an alert alias that Debian leaves commented out. Root is the exception on Debian: /root/.bashrc comes from the base-files package (/usr/share/base-files/dot.bashrc), in which every line is a comment. That is why on a stock Debian install root gets a plain prompt and no history tuning while your sudo user gets the full file.

What to put in ~/.bashrc, and what goes in ~/.profile

A simple rule: things that only matter while you type go into ~/.bashrc; settings that every program of your session should inherit go into ~/.profile.

SettingFileWhy
Aliases and functions you type~/.bashrcInteractive only; Debian and Ubuntu also read ~/.bash_aliases from it
Prompt (PS1), history, shopt options~/.bashrcBash-specific and interactive
PATH additions, EDITOR, LANG~/.profileRead once per login, also by sh and graphical sessions
Variables a remote command needs~/.bashrc above the guardssh host command reads nothing else
Settings for every user/etc/bash.bashrc or /etc/profile.d/*.shSystem-wide versions of the two files

These additions go below the stock content. We loaded them in an interactive bash 5.2 to confirm each one takes effect:

~/.bashrc additions
HISTSIZE=50000                  # lines kept in memory
HISTFILESIZE=100000             # lines kept in ~/.bash_history
HISTTIMEFORMAT='%F %T  '        # history shows date and time of each command
PROMPT_COMMAND='history -a'     # write each command to the file right away
shopt -s globstar               # ** matches files in all subdirectories

# green user@host, blue directory; \[ \] mark the colour codes as zero width
PS1='\[\e[1;32m\]\u@\h\[\e[0m\]:\[\e[1;34m\]\w\[\e[0m\]\$ '

mkcd() { mkdir -p "$1" && cd "$1"; }         # make a directory and enter it

Without the \[ and \] around colour codes, bash counts them as visible characters and long command lines wrap in the wrong place; Debian's bash README gives the same advice for prompts that do not display correctly. If you would rather move to zsh with a ready-made theme, that is a different file altogether: zsh reads ~/.zshrc, never ~/.bashrc.

Edit and reload: source, exec bash or a new terminal

  • source ~/.bashrc runs the file again in the current shell. It adds and overwrites, but it cannot take anything away: in our test an alias deleted from the file was still defined after source. Lines like PATH="$PATH:$HOME/bin" also grow each time you source.
  • exec bash replaces the shell with a fresh interactive one. Removed aliases and functions are gone, exported variables survive.
  • A new terminal or a new SSH login starts from scratch and is the real test of what the next session will see.

Fix a broken ~/.bashrc

A missing fi, a stray quote or a bad PATH line can leave every new shell printing errors or missing commands. On a remote server, keep a second SSH session open while you edit dotfiles, so a mistake never locks you out.

  1. 1Find the line

    bash -n parses the file without running it:

    Example output · path shortened
    $ bash -n ~/.bashrc
    /home/demo/.bashrc: line 118: syntax error: unexpected end of file

    "Unexpected end of file" means an if, case, quote or brace was opened and never closed; the line number is where bash gave up, so look above it.

  2. 2Get a shell that skips it

    Locally: bash --norc. Over SSH: ssh -t user@host bash --norc --noprofile. The shell sshd starts to run that command still reads ~/.bashrc on Debian and Ubuntu, but it returns at the guard, so this works unless the damage sits above the guard. If even that fails, fix the file from another account with sudo, or from the server's console.

  3. 3Repair or restore the default
    bash
    cp ~/.bashrc ~/.bashrc.broken     # keep your version for reference
    cp /etc/skel/.bashrc ~/.bashrc    # back to the distribution default
    exec bash

    Then copy your own lines back from ~/.bashrc.broken one block at a time, running bash -n after each. If commands such as ls are suddenly "not found", a PATH line is broken; the PATH section of the environment variable guide shows how to put the standard list back for the current shell first.

A slow shell start

If a new shell takes seconds to appear, run bash -x -i -c exit 2>&1 | less and look for the command that stalls. Likely suspects are blocks that installers append to the file, such as the setup of a version manager or of conda, which run at every start whether you need them or not. If one of them is the cause, load that tool on demand with a function instead.

Two related tricks live in the same file: the directory stack from pushd and popd becomes handy with a short alias such as alias d='dirs -v', and if you edit ~/.bashrc in vim for the first time, how to exit vim is worth a look first. On a new server, set this up for the sudo user you work as rather than for root.

Frequently asked

What is the difference between .bashrc and .bash_profile?

Bash reads ~/.bashrc for interactive shells that are not login shells, such as a new terminal window, and ~/.bash_profile (or ~/.bash_login or ~/.profile, whichever exists first) for login shells such as an SSH login. A login shell does not read ~/.bashrc on its own, so ~/.bash_profile should contain the line if [ -f ~/.bashrc ]; then . ~/.bashrc; fi.

How do I reload .bashrc without logging out?

Run source ~/.bashrc, or the short form . ~/.bashrc, in the shell you want to update. Sourcing adds and overwrites but does not remove: an alias you deleted from the file stays defined until you run exec bash or open a new terminal.

Why is my .bashrc not loaded when I connect over SSH?

An SSH login is a login shell, so bash reads ~/.bash_profile or ~/.profile instead. On Debian and Ubuntu the default ~/.profile sources ~/.bashrc, but a ~/.bash_profile without that line makes bash skip ~/.profile entirely. Also check that your login shell is bash with getent passwd $USER.

How do I restore the default .bashrc?

Copy the distribution's template over your file: cp ~/.bashrc ~/.bashrc.broken, then cp /etc/skel/.bashrc ~/.bashrc, then exec bash. On Debian, root's original file is /usr/share/base-files/dot.bashrc, which contains only comments.

Related articles

All guides