Take the 2-minute tour ×
Unix & Linux Stack Exchange is a question and answer site for users of Linux, FreeBSD and other Un*x-like operating systems.. It's 100% free, no registration required.

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?

share|improve this question
Make sure you have the $ZDOTDIR properly defined. zsh.sourceforge.net/Intro/intro_3.html –  ramonovski Mar 2 '12 at 17:58
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. –  Frank Terbeck Mar 24 '12 at 14:46

4 Answers 4

up vote 26 down vote accepted

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 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 everytime 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.)

share|improve this answer
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? –  Amelio Vazquez-Reina Mar 10 '12 at 20:26
I extended the original answer to address those questions as well. –  Frank Terbeck Mar 10 '12 at 22:43
Please answer more zsh questions. +1 –  chiggsy Mar 24 '12 at 3:04
“you will always define in function that is named like the file in the file and call that function at the end of the file”: why so? –  Hibou57 Aug 13 '14 at 21:39
Hibou57: (Aside: That's a typo there, should be "define a function", that's fixed now.) I thought that was clear, when you take the code snippet that follows into consideration. Anyway, I've added a paragraph that spells the reason out a bit more literally. –  Frank Terbeck Aug 15 '14 at 12:04

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.

share|improve this answer

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

share|improve this answer
Thanks, but what is the role of FPATH and autoload then? Why do I also need to source the file? See my updated question. –  Amelio Vazquez-Reina Mar 2 '12 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".

share|improve this answer
Thanks, but what is the role of FPATH and autoload then? Why do I also need to source the file? See my updated question. –  Amelio Vazquez-Reina Mar 2 '12 at 18:16

Your Answer


By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.