I am having a hard time defining and running my own shell functions in zsh. I followed the instructions on the official documentation and tried with easy example first, but I failed to get it work.

I have a folder:


In this folder I have a file called functions_1 with rwx user permissions. In this file I have the following shell function defined:

my_function () {
echo "Hello world";

I defined FPATH to include the path to the folder ~/.my_zsh_functions:

export FPATH=~/.my_zsh_functions:$FPATH

I can confirm that the folder .my_zsh_functions is in the functions path with echo $FPATH or echo $fpath

However, if I then try the following from the shell:

> autoload my_function
> my_function

I get:

zsh: my_test_function: function definition file not found

Is there anything else I need to do to be able to call my_function ?


The answers so far suggest sourcing the file with the zsh functions. This makes sense, but I am bit confused. Shouldn't zsh know where those files are with FPATH? What is the purpose of autoload then?

  • Make sure you have the $ZDOTDIR properly defined. zsh.sourceforge.net/Intro/intro_3.html
    – ramonovski
    Commented Mar 2, 2012 at 17:58
  • 2
    The value of $ZDOTDIR is not related to this problem. The variable defines where zsh is looking for a user's configuration files. If it is unset $HOME is used instead, which is the right value for almost everybody. Commented Mar 24, 2012 at 14:46
  • I agree that sourcing isn't the zsh way, but if you intend to use your dotfiles (or parts of them) across your zsh and bash configs, then using source is the only option that you have.
    – kapad
    Commented Oct 20, 2020 at 9:16
  • On bash compatibility: This question is concerned with zsh's loadable function system. It has nothing to do with bash (and to my knowledge has not equivalent in bash). Sourcing files from $FPATH either defeats autoloading or plainly does not work. Commented Dec 24, 2022 at 9:42

5 Answers 5


In zsh, the function search path ($fpath) defines a set of directories, which contain files that can be marked to be loaded automatically when the function they contain is needed for the first time.

Zsh has two modes of autoloading files: Zsh's native way and another mode that resembles ksh's autoloading. The latter is active if the KSH_AUTOLOAD option is set. Zsh's native mode is the default and I will not discuss the other way here (see "man zshmisc" and "man zshoptions" for details about ksh-style autoloading).

Okay. Say you got a directory `~/.zfunc' and you want it to be part of the function search path, you do this:

fpath=( ~/.zfunc "${fpath[@]}" )

That adds your private directory to the front of the search path. That is important if you want to override functions from zsh's installation with your own (like, when you want to use an updated completion function such as `_git' from zsh's CVS repository with an older installed version of the shell).

It is also worth noting, that the directories from `$fpath' are not searched recursively. If you want your private directory to be searched recursively, you will have to take care of that yourself, like this (the following snippet requires the `EXTENDED_GLOB' option to be set):


It may look cryptic to the untrained eye, but it really just adds all directories below `~/.zfunc' to `$fpath', while ignoring directories called "CVS" (which is useful, if you're planning to checkout a whole function tree from zsh's CVS into your private search path).

Let's assume you got a file `~/.zfunc/hello' that contains the following line:

printf 'Hello world.\n'

All you need to do now is mark the function to be automatically loaded upon its first reference:

autoload -Uz hello

"What is the -Uz about?", you ask? Well, that's just a set of options that will cause `autoload' to do the right thing, no matter what options are being set otherwise. The `U' disables alias expansion while the function is being loaded and the `z' forces zsh-style autoloading even if `KSH_AUTOLOAD' is set for whatever reason.

After that has been taken care of, you can use your new `hello' function:

zsh% hello
Hello world.

A word about sourcing these files: That's just wrong. If you'd source that `~/.zfunc/hello' file, it would just print "Hello world." once. Nothing more. No function will be defined. And besides, the idea is to only load the function's code when it is required. After the `autoload' call the function's definition is not read. The function is just marked to be autoloaded later as needed.

And finally, a note about $FPATH and $fpath: Zsh maintains those as linked parameters. The lower case parameter is an array. The upper case version is a string scalar, that contains the entries from the linked array joined by colons in between the entries. This is done, because handling a list of scalars is way more natural using arrays, while also maintaining backwards compatibility for code that uses the scalar parameter. If you choose to use $FPATH (the scalar one), you need to be careful:


will work, while the following will not:


The reason is that tilde expansion is not performed within double quotes. This is likely the source of your problems. If echo $FPATH prints a tilde and not an expanded path then it will not work. To be safe, I'd use $HOME instead of a tilde like this:


That being said, I'd much rather use the array parameter like I did at the top of this explanation.

You also shouldn't export the $FPATH parameter. It is only needed by the current shell process and not by any of its children.


Regarding the contents of files in `$fpath':

With zsh-style autoloading, the content of a file is the body of the function it defines. Thus a file named "hello" containing a line echo "Hello world." completely defines a function called "hello". You're free to put hello () { ... } around the code, but that would be superfluous.

The claim that one file may only contain one function is not entirely correct, though.

Especially if you look at some functions from the function based completion system (compsys) you'll quickly realise that that is a misconception. You are free to define additional functions in a function file. You are also free to do any sort of initialisation, that you may need to do the first time the function is called. However, when you do you will always define a function that is named like the file in the file and call that function at the end of the file, so it gets run the first time the function is referenced.

If - with sub-functions - you didn't define a function named like the file within the file, you'd end up with that function having function definitions in it (namely those of the sub-functions in the file). You would effectively be defining all your sub-functions every time you call the function that is named like the file. Normally, that is not what you want, so you'd re-define a function, that's named like the file within the file.

I'll include a short skeleton, that will give you an idea of how that works:

# Let's again assume that these are the contents of a file called "hello".

# You may run arbitrary code in here, that will run the first time the
# function is referenced. Commonly, that is initialisation code. For example
# the `_tmux' completion function does exactly that.
echo initialising...

# You may also define additional functions in here. Note, that these
# functions are visible in global scope, so it is paramount to take
# care when you're naming these so you do not shadow existing commands or
# redefine existing functions.
hello_helper_one () {
    printf 'Hello'

hello_helper_two () {
    printf 'world.'

# Now you should redefine the "hello" function (which currently contains
# all the code from the file) to something that covers its actual
# functionality. After that, the two helper functions along with the core
# function will be defined and visible in global scope.
hello () {
    printf '%s %s\n' "$(hello_helper_one)" "$(hello_helper_two)"

# Finally run the redefined function with the same arguments as the current
# run. If this is left out, the functionality implemented by the newly
# defined "hello" function is not executed upon its first call. So:
hello "$@"

If you'd run this silly example, the first run would look like this:

zsh% hello
Hello world.

And consecutive calls will look like this:

zsh% hello
Hello World.

I hope this clears things up.

(One of the more complex real-world examples that uses all those tricks is the already mentioned `_tmux' function from zsh's function based completion system.)

  • Thanks Frank! I read in the other answers that I can only define one function per file, is that right? I noticed you didn't use the syntax my_function () { } in your Hello world example. If the syntax is not needed, when would it be useful to use it? Commented Mar 10, 2012 at 20:26
  • 3
    I extended the original answer to address those questions as well. Commented Mar 10, 2012 at 22:43
  • 1
    Here is more info from your site, thanks.
    – Timo
    Commented Nov 7, 2017 at 15:25
  • 4
    What a superb answer. Thank you! Commented May 15, 2020 at 11:51
  • 1
    vfclists: It's important to understand what the autoload does: It marks a function to be loaded automatically when referenced first. So, if you just want to try things out, you can do it from the command line. If you want a function to be marked for autoloading in each interactive instance of zsh, you can put it into your ~/.zshrc. Commented Oct 18, 2020 at 19:53

The name of the file in a directory named by an fpath element must match the name of the autoloadable function it defines.

Your function is named my_function and ~/.my_zsh_functions is the intended directory in your fpath, so the definition of my_function should be in the file ~/.my_zsh_functions/my_function.

The plural in your proposed filename (functions_1) indicates that you were planning on putting multiple functions in the file. This is not how fpath and autoloading work. You should have one function definition per file.

  • Thanks Chris! Used this to do this and now I can actually use it :) I had to rename my file >.<
    – SumNeuron
    Commented Mar 21, 2023 at 15:39

Sourcing definitely isn't the right approach, since what you seem to want is to have lazy initialized functions. That's what autoload is for. Here's how you accomplish what you're after.

In your ~/.my_zsh_functions, you say you want to put a function called my_function that echos "hello world". But, you wrap it in a function call, which isn't how this works. Instead, you need to make a file called ~/.my_zsh_functions/my_function. In it, just put echo "Hello world", not in a function wrapper. You could also do something like this if you really do prefer to have the wrapper.

# ~/.my_zsh_functions/my_function
__my_function () {
    echo "Hello world";
# you have to call __my_function
# if this is how you choose to do it

Next, in your .zshrc file, add the following:

fpath=(~/.my_zsh_functions $fpath);
autoload -U ~/.my_zsh_functions/my_function

When you load a new ZSH shell, type which my_function. You should see this:

my_function () {
    # undefined
    builtin autoload -XU

ZSH just stubbed out my_function for you with autoload -X. Now, run my_function by just typing my_function. You should see Hello world print out, and now when you run which my_function you should see the function filled in like this:

my_function () {
    echo "Hello world"

Now, the real magic comes when you set up your whole ~/.my_zsh_functions folder to work with autoload. If you want every file you drop in this folder to work like this, change what you put in your .zshrc to something this:

# add ~/.my_zsh_functions to fpath, and then lazy autoload
# every file in there as a function
fpath=(~/.my_zsh_functions $fpath);
autoload -U $fpath[1]/*(.:t)
  • 2
    On Mac OS 10.15.2 with zsh 5.7.1 I had to add a $ infront of fpath like: autoload -U $fpath[1]/*(.:t) Commented Feb 25, 2020 at 14:38
  • What happens if there is a a directory in the directory I am autoloading every file from?
    – trallnag
    Commented Oct 17, 2021 at 22:31
  • You can dot that, but you'll want to use extended globbing and the double star syntax: setopt extended_glob; autoload -U $fpath[1]/**/*(.:t)
    – mattmc3
    Commented Oct 20, 2021 at 16:11
  • Why you didn't use autoload -Uz but only autoload -U? IIRC, these two options are better to be used together.
    – Niing
    Commented Mar 16, 2023 at 10:17
  • @Niing - If there's a chance KSH_AUTOLOAD was set somewhere in your config and you don't actually want that for your autoload functions, then sure - autoload -Uz ensures you are in Zsh mode when autoloading. But for most people's config that's probably not a real problem.
    – mattmc3
    Commented Mar 16, 2023 at 20:25

give source ~/.my_zsh_functions/functions1 in the terminal and the evaluate my_function, now you will be able to call the function

  • 3
    Thanks, but what is the role of FPATH and autoload then? Why do I also need to source the file? See my updated question. Commented Mar 2, 2012 at 18:17

You can "load" a file with all your functions in your $ZDOTDIR/.zshrc like this:

source $ZDOTDIR/functions_file

Or can use a dot "." instead of "source".

  • 1
    Thanks, but what is the role of FPATH and autoload then? Why do I also need to source the file? See my updated question. Commented Mar 2, 2012 at 18:16

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .