How to Install and Get Started with Oils

Updated

Oils ships as a single binary called oils-for-unix that contains both shells: OSH, which runs your existing shell scripts, and YSH, a newer language aimed at Python and JavaScript users who want to avoid traditional shell. To get started, download the latest release from the project's release page, then run the binary as either osh or ysh. The site's Install and Docs links are the canonical starting points, and the homepage points to a "Latest Release" plus an "All Releases" page under /release/latest/.

What you get in one download

The homepage states that OSH and YSH live inside the same 2 MB oils-for-unix binary. That means you don't install two separate tools or pick a variant at download time — the same file gives you both runtimes.

Shell Who it's for What it does
OSH Anyone with existing shell scripts Runs your current scripts, with stricter error detection
YSH Python and JavaScript users who avoid shell A new shell language for scripting without traditional shell quirks

The homepage illustrates the OSH difference with a short example:

echo "hello $oops"
^~~~~
fatal: Undefined variable 'oops'

Where a conventional shell would silently expand an unset variable, OSH reports it as a fatal error. That behavior is the practical reason to try OSH on scripts you already have.

Install steps

  1. Open the Oils site and follow the Install link, or go directly to the releases page at /release/latest/ for the newest build and /release/ (linked as "All Releases") for older ones.
  2. Download the oils-for-unix binary for your platform from that release page.
  3. Make it executable and place it somewhere on your PATH, or invoke it by path.
  4. Run it as osh to execute existing scripts, or as ysh to write new code in the YSH language.

The site does not publish pricing or payment details, so treat download and access terms as something to confirm on the release page itself rather than assuming they are free or unrestricted.

Verify the install

The clearest check is to reproduce the homepage's own example. Run a script or command that references an undefined variable and confirm you get the fatal: Undefined variable message rather than a silent empty expansion. If you see that error, OSH is running as intended.

For YSH, the homepage shows a JSON-reading example:

ysh$ json read < x.json
ysh$ = _reply
(Dict) {shell: "ysh", fun: true}

This demonstrates two things at once: YSH can parse JSON directly from standard input, and = _reply prints the value along with its type. Running this against a small JSON file is a quick way to confirm YSH is working.

Where to go next

  • Oils Reference — the homepage links a reference section for looking up syntax and builtins.
  • Docs — linked from the top navigation alongside Install and Blog.
  • Blog — posts cover topics like the FAQ, "Why Create a New Unix Shell?", "The Simplest Explanation", "A Tour of YSH", and "YSH vs. Shell Idioms". These are the fastest route from "installed" to "productive", especially the YSH tour and the idioms comparison if you're deciding between OSH and YSH.
  • Source and editor support — the repo is oils-for-unix/oils on GitHub, with oils.vim for editor support.

Getting help

The project lists several channels:

  • Zulip at oilshell.zulipchat.com, with #oil-help for user questions, #oil-discuss-public for general discussion, and #oil-dev for code changes (login required for that one).
  • Reddit at /r/oilsforunix.
  • Mastodon and Twitter as @oilsforunix, plus an RSS feed, for blog notifications.
  • Email to the maintainer at the address listed on the site.
  • Contributing — the homepage points to a # help-wanted section suggesting places to start changing the code.

Common sticking points

  • One binary, two names. If osh or ysh isn't recognized, you're likely invoking the binary directly rather than through the shell name you intended. Check how the release page tells you to call it.
  • OSH is stricter than bash on purpose. Scripts that rely on unset variables expanding to empty will fail under OSH. That's the feature, not a bug — but it means some existing scripts need a fix before they run cleanly.
  • YSH is a different language, not a bash mode. If you're coming from Python or JavaScript, start with the YSH tour and the idioms comparison rather than translating shell habits directly.