---
title: 'A better ls on macOS: use eza, but not as an alias'
description: >-
  Replace the macOS ls with eza in one line of zsh. An alias breaks when you pass it a directory. A
  shell function doesn't.
url: https://expiredqueues.com/better-ls-macos-eza/
markdown: https://expiredqueues.com/better-ls-macos-eza/index.md
date: '2024-04-16T09:00:00.000Z'
image: https://expiredqueues.com/images/og/better-ls-macos-eza-6c91eaae.jpg
---

Developer Tools posts tools

# A better ls on macOS: use eza, but not as an alias

16 April 2024 Updated 13 November 2026 By Adrian Noel 6 min read

On this page

1. [Why eza](#why-eza)
2. [1. Install a Nerd Font](#1-install-a-nerd-font)
3. [2. Install eza](#2-install-eza)
4. [3. Add a theme](#3-add-a-theme)
5. [4. Use a function, not an alias](#4-use-a-function-not-an-alias)
6. [5. Put it at the end of `.zshrc`](#5-put-it-at-the-end-of-zshrc)
7. [6. Try it](#6-try-it)
8. [Run the real `ls`](#run-the-real-ls)
9. [Why `--color=always` is there](#why-color-always-is-there)
10. [The final setup](#the-final-setup)

I spend most of my day in a terminal. I don't need `ls` to tell me who owns a file.

This is the front end of one of my projects in macOS `ls -l`:

```text
total 640
-rw-r--r--@  1 adrian  staff    6739 Apr 15 09:12 AGENTS.md
drwxr-xr-x@ 14 adrian  staff     448 Apr 16 08:41 app
drwxr-xr-x@ 15 adrian  staff     480 Apr 16 08:41 components
-rw-r--r--@  1 adrian  staff     382 Apr 15 09:12 eslint.config.mjs
drwxr-xr-x@  5 adrian  staff     160 Apr 16 08:41 lib
-rw-r--r--@  1 adrian  staff     251 Apr 15 09:12 next-env.d.ts
-rw-r--r--@  1 adrian  staff     129 Apr 14 22:07 next.config.ts
drwxr-xr-x@ 16 adrian  staff     512 Apr 15 09:12 node_modules
-rw-r--r--@  1 adrian  staff     660 Apr 15 09:12 package.json
-rw-r--r--@  1 adrian  staff  132858 Apr 16 16:14 pnpm-lock.yaml
-rw-r--r--@  1 adrian  staff     146 Apr 14 22:07 postcss.config.mjs
drwxr-xr-x@  3 adrian  staff      96 Apr 14 22:07 public
-rw-r--r--@  1 adrian  staff     275 Apr 16 23:16 README.md
drwxr-xr-x@  4 adrian  staff     128 Apr 15 09:12 src
-rw-r--r--@  1 adrian  staff     698 Apr 14 22:07 tsconfig.json
-rw-r--r--@  1 adrian  staff  155028 Apr 16 08:41 tsconfig.tsbuildinfo
```

Permissions, link count, owner, group, size and date all come before the filename. Most of the time I'm looking for a file.

I'd rather see this:

[![A zsh session: ls listing two directories, then ls website listing the same project with a folder or file-type icon in front of every name.](https://expiredqueues.com/images/opt/eza-ls-directory-argument-320.jpeg)](https://expiredqueues.com/images/opt/eza-ls-directory-argument-1440.jpeg "Open the full-size image")

The same directory, and the one above it. Directories first, icons by file type, one entry per line.

This setup replaces `ls` in your interactive shell with [eza](https://github.com/eza-community/eza). It adds icons and colors. It also keeps working when you pass arguments, which an alias doesn't.

## Why eza

eza is the maintained fork of `exa`. It gives you:

- directories grouped first
- optional icons
- file-type colors
- tree views
- sorting options
- Git integration
- the same arguments as `ls`

The last one matters most. It still feels like `ls`.

## 1. Install a Nerd Font

Icons need a font with the Nerd Font glyphs. Check what you have:

```bash
system_profiler SPFontsDataType | grep -i "nerd"
```

If nothing comes back, install Fira Code:

```bash
brew install --cask font-fira-code-nerd-font
```

### Set the font in your terminal

Your editor font and your terminal font are separate settings. In VS Code:

```json
{
  "editor.fontFamily": "Fira Code",
  "terminal.integrated.fontFamily": "FiraCode Nerd Font",
  "terminal.integrated.lineHeight": 1.2
}
```

Run **Developer: Reload Window** from the Command Palette. You don't need to restart VS Code.

In [iTerm2](https://expiredqueues.com/iterm2-mac-natural-text/index.md), go to **Settings → Profiles → Text → Font** and pick **FiraCode Nerd Font**.

## 2. Install eza

```bash
which eza || brew install eza
```

Check that it runs:

```bash
eza -1 --group-directories-first
```

`-1` puts each entry on its own line. Without it, eza prints a grid.

## 3. Add a theme

**Added October 2024:** eza reads a theme file from version 0.19.2. On an older build, skip this section. Everything else still works.

Create the config directory:

```bash
mkdir -p ~/.config/eza
```

Download a theme. I use Tokyo Night:

```bash
curl -L https://raw.githubusercontent.com/eza-community/eza-themes/refs/heads/main/themes/tokyonight.yml \
  -o ~/.config/eza/theme.yml
```

Add this line to `~/.zshrc` so that eza finds the theme:

```bash
export EZA_CONFIG_DIR="$HOME/.config/eza"
```

Reload and confirm:

```bash
source ~/.zshrc
echo $EZA_CONFIG_DIR
```

## 4. Use a function, not an alias

This alias looks right:

```bash
alias ls='eza -1 --icons=always --color=always --group-directories-first | sed "s/^/ › /"'
```

It breaks when you pass a directory:

```bash
ls website
```

A shell alias is text substitution. The command becomes:

```bash
eza -1 --icons=always --color=always --group-directories-first | sed "s/^/ › /" website
```

`website` is now an argument to `sed`. When `sed` gets a file operand, it stops reading `stdin`. eza's listing is thrown away.

For a directory, you get nothing. For a file, you get its contents:

```text
 › {
 ›   "name": "@pwtray/website",
 ›   "version": "1.0.1",
```

`ls -la` fails with an error:

```text
sed: -la: No such file or directory
```

Every argument after the command name goes to `sed` the same way.

Use a shell function:

```bash
unalias ls 2>/dev/null
function ls { eza -1 --icons=always --color=always --group-directories-first "$@" | sed 's/^/ › /'; }
```

`"$@"` is the fix. It passes your arguments to eza, before the pipe. `ls`, `ls website`, `ls -a` and `ls website/app -T -L 2` all work.

## 5. Put it at the end of `.zshrc`

If you use Oh My Zsh or another framework, define the function **after** the framework loads. Otherwise the framework's own `ls` alias wins.

```bash
# plugins, framework, PATH, etc.

export EZA_CONFIG_DIR="$HOME/.config/eza"

unalias ls 2>/dev/null
function ls { eza -1 --icons=always --color=always --group-directories-first "$@" | sed 's/^/ › /'; }
```

Keep the `unalias` line. Oh My Zsh and other frameworks define `ls` as an alias. zsh expands an existing alias inside your function definition, and you get a syntax error:

```bash
parse error near `()'
```

Use the `function` keyword too. zsh never alias-expands the name after `function`. It does expand the name in the `ls() { ... }` form.

Reload the shell:

```bash
source ~/.zshrc
```

## 6. Try it

```bash
ls
```

You get the listing from the first screenshot. Icons appear if your terminal font has them. `ls website` lists the `website` directory the same way.

eza's own flags still work:

```bash
ls -a           # hidden files
ls -T -L 2      # a two-level tree
ls -s modified  # sorted by modification time
ls -D           # directories only
ls | grep .md   # and it still pipes
```

You can mix flags and paths:

[![ls website/app -T -L 2 drawing a two-level tree of a Next.js app directory, with connector lines and file-type icons.](https://expiredqueues.com/images/opt/eza-ls-tree-view-320.jpeg)](https://expiredqueues.com/images/opt/eza-ls-tree-view-1440.jpeg "Open the full-size image")

`ls website/app -T -L 2` passes a path and two eza flags straight through `"$@"`.

## Run the real `ls`

Either of these runs the system `ls`:

```bash
command ls -la
\ls -la
```

The function exists only in your interactive shell. It doesn't change `/bin/ls`. Scripts that run outside that shell don't see it.

## Why `--color=always` is there

Most command-line tools emit color codes only when stdout is a terminal. When stdout is a pipe, they turn color off.

The function pipes eza through `sed`:

```text
eza → sed → terminal
```

eza sees a pipe, so it would drop the colors and the icons. `--color=always` and `--icons=always` turn them back on.

The escape codes are now part of the output. A tool that understands ANSI handles them:

```bash
ls | less -R
```

A tool that doesn't will print the codes. Use `command ls` when another program parses the output.

## The final setup

```bash
export EZA_CONFIG_DIR="$HOME/.config/eza"

unalias ls 2>/dev/null
function ls { eza -1 --icons=always --color=always --group-directories-first "$@" | sed 's/^/ › /'; }
```

### You might be interested in:

- [Git commands I wish I knew early](https://expiredqueues.com/git-commands-i-wish-i-knew-early/index.md) - the other half of the same terminal.
- [The Pragmatic Programmer](https://expiredqueues.com/books/the-pragmatic-programmer/index.md) - where the case for small, local, invisible shell automation comes from.

**Expired Queues is on YouTube.** Short videos on the same topics as this blog.

[Watch on YouTube](https://www.youtube.com/@expiredqueues)

[Previously Stop scrolling the Network panel: filter it](https://expiredqueues.com/filter-chrome-devtools-network-requests/index.md) [Next Home network setup that just stays quiet](https://expiredqueues.com/home-network-setup/index.md)

## Structured data

```json
{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "A better ls on macOS: use eza, but not as an alias",
  "description": "Replace the macOS ls with eza in one line of zsh. An alias breaks when you pass it a directory. A shell function doesn't.",
  "datePublished": "2024-04-16T09:00:00.000Z",
  "dateModified": "2026-11-13T00:00:00.000Z",
  "author": {
    "@type": "Person",
    "name": "Adrian Noel",
    "url": "https://expiredqueues.com/about/"
  },
  "publisher": {
    "@type": "Person",
    "name": "Adrian Noel"
  },
  "mainEntityOfPage": "https://expiredqueues.com/better-ls-macos-eza/",
  "image": "https://expiredqueues.com/images/2024/eza-ls-directory-argument.png",
  "keywords": "posts, tools, macos, terminal, tips-tricks",
  "articleSection": "Developer Tools"
}
```
