Skip to main content

Funky takes shell functions to the next level by making them easier to define, more flexible, and more interactive.

Project description

funky Tweet

Funky takes shell functions to the next level by making them easier to define, more flexible, and more interactive.

Project Version Python Versions Package Health

Tests: pytest Tests: pytest Types: mypy pylint flake8 Code Style: black Imports: isort

Test Workflow Lint Workflow Publish Workflow Coverage


Table of Contents


Funks are manipulated using the funky and gfunky commands. These commands have the same user interface, which is specified in the Command-line Interface section. The difference between the two commands is treated in the Local vs Global section.

Local vs Global

Local funks are stored using a hidden database file that is located in the same directory where the funk was created. These can be manipulated using the action command options described above. Once created, a local funk can be used just like any other command or normal funk---as long as you have activated the provided shell extension (see Additional Install Steps) and are inside of the directory where the local funk was originally defined.

Global funks, on the other hand, are stored in your home directory (/home/<user>) and can be used from any directory. Local funks can be used to override global funk definitions.

Local and global funks can be manipulated (created, removed, edited, renamed, etc.) by using the funky and gfunky commands, respectively.

Funk Definition Shortcuts

Normally when defining a funk, the provided raw definition (the final contents of the temp file) is inserted directly into the generated function definition. However, funky does try to make some alterations to the original funk definition when doing so is convenient. These funky definition shortcuts can make defining funks faster:

Special cd Funks

A funk definition of the form @./relative/path/to/directory will be automatically changed to

cd /absolute/path/to/directory/"$@" || return 1

Simulate Shell Variables

A funk definition of the form "Some string here..." will be automatically changed to

echo "Some string here..." "$@"

This allows you to use funks to simulate shell variables via command substitution.

The "$@" Special Parameter

This project originally used aliases. The decision to migrate to shell functions was made based on the fact that shell functions are far more capable than aliases. Moreover, there is very little benefit to using aliases over shell functions.

With that said, actual aliases do have one appeal over shell functions. When you use an alias, any arguments that you pass to it are automatically passed to the command definition (at runtime, aliases are just substituted with their definitions). For the purpose of emulating this behavior when it would typically be desired, a funk defined using a single-line command definition that does NOT already contain argument variables (e.g. does not contain $0, $1, ..., $9, $*, or $@) will automatically have the "$@" special parameter appended to its definition. This allows for the same automatic argument handling that you would expect from an alias.

See the official Bash docs for more information on Bash's special parameters.

Articles / Blog Posts

With the goal of listing alternative sources of documentation / tutorials, this section will be used to track any articles or blog posts which mention funky:


Using pip to Install

To install funky, run the following commands in your terminal (replace SHELL with either bash or zsh):

python3 -m pip install --user pyfunky  # install funky
python3 -m funky --setup-shell SHELL  # hook funky into your shell

This is the preferred method to install funky, as it will always install the most recent stable release.

If you don't have pip installed, this Python installation guide can guide you through the process.

Building from Source

You can either clone the public repository:

$ git clone git://

Or download the tarball:

$ curl  -OL

Once you have a copy of the source, you can install funky by running:

make install

The last thing you need to do is hook funky into your shell of choice, which can be accomplished with the following command (replace SHELL with either bash or zsh):

python3 -m funky --setup-shell SHELL

Similar Projects

  • desk - A lightweight workspace manager for the shell.
  • smartcd - Alter your bash (or zsh) environment as you cd.
  • direnv - is an extension for your shell. It augments existing shells with a new feature that can load and unload environment variables depending on the current directory.


Pull requests are welcome. See for more information.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyfunky-3.5.5.tar.gz (28.2 kB view hashes)

Uploaded source

Built Distribution

pyfunky-3.5.5-py2.py3-none-any.whl (18.0 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page