oils.pub

OSH and YSH are the two languages inside Oils, and they ship in the same 2 MB oils-for-unix binary. OSH runs your existing shell scripts, so it is the one to use when you need bash compatibility. YSH is a newer language aimed at Python and JavaScript users who avoid shell, and it adds features like JSON handling that plain shell does not have. Pick OSH to run what you already have; pick YSH to write new code with a cleaner, more structured language.

OSH: run existing shell scripts

OSH is the compatibility layer. The Oils homepage describes it as the "upgrade path from bash," and its job is to execute the shell scripts you already have.

The example on the site shows what that means in practice:

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

Instead of silently expanding an unset variable to an empty string, OSH reports it as a fatal error. That is the "better language and runtime" part: you keep running your scripts, but the runtime catches mistakes that bash would let pass.

Choose OSH when:

• You have existing bash or POSIX shell scripts you want to run without rewriting them.
• You want stricter error detection on the scripts you already depend on.
• You are migrating gradually and want a drop-in path rather than a new language.

YSH: for Python and JavaScript users who avoid shell

YSH is the second language in the same binary, and the homepage frames it directly: "YSH is for Python and JavaScript users who avoid shell!"

The distinction is about who the language is for. If you come from Python or JavaScript and find shell syntax awkward, YSH is the part of Oils designed for you. It is not a compatibility layer for old scripts; it is a language you write new code in.

The site's example shows the kind of structured data handling that is painful in plain shell:

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

Here json read parses JSON from standard input, and = _reply prints the resulting value with its type shown as (Dict). In a traditional shell, reading and inspecting JSON usually means piping through an external tool and losing type information. YSH handles it as a first-class value.

Choose YSH when:

• You are writing new scripts and prefer a language closer to Python or JavaScript.
• You need to read, inspect, or manipulate structured data such as JSON.
• You want typed values rather than everything being a string.

Side-by-side

How they relate

The two are not competing products you install separately. The homepage states that "OSH and YSH live inside the same 2 MB oils-for-unix binary," so installing Oils gives you both. You decide which language to use per script or per task.

A practical way to think about it: OSH is the bridge from where you are (existing shell scripts), and YSH is the destination if you want a better language for new work. You can start with OSH to run what you have, then adopt YSH for new scripts without changing your installation.

Where to go next

• Install and reference material are linked from the Oils site under Install, Docs, and the Oils Reference.
• The blog covers background such as "Why Create a New Unix Shell?" and a "Tour of YSH," which are useful if you want the reasoning behind the design.
• For questions, the site points to Zulip at oilshell.zulipchat.com, with #oil-help for user questions and #oil-discuss-public for general discussion.
• Source and editor support are on GitHub at oils-for-unix/oils, including oils.vim editor support.

Oils was created to give shell users an upgrade path from bash to a better language and runtime — one that keeps your existing shell scripts working while offering a stricter, more modern alternative. It solves two distinct problems at once: the fragility of traditional shell scripting (like silent failures on undefined variables), and the awkwardness shell poses for people coming from Python or JavaScript. The project's own framing is explicit: OSH runs your existing shell scripts, while YSH is "for Python and JavaScript users who avoid shell."

The two problems Oils targets

1. Shell scripts fail in ways that are hard to catch

Traditional shells are permissive by default. A typo in a variable name often expands to an empty string instead of raising an error, so bugs surface far from their cause. Oils' homepage illustrates this directly with a fatal error on an undefined variable:

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

That behavior is the point. Instead of silently substituting nothing, the runtime stops and points at the problem. This is the "better runtime" half of the project's stated goal — catching mistakes at the moment they happen rather than downstream.

2. Shell is unfriendly to programmers from other languages

The second problem is audience fit. YSH is positioned for people who know Python or JavaScript but avoid shell because of its quoting rules, string handling, and data structures. The homepage example shows structured data flowing through the shell:

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

Here JSON is parsed into a typed Dict rather than being handled as unstructured text — a capability that maps onto how Python and JavaScript users already expect to work with data.

How the two halves fit together

Both live inside the same oils-for-unix binary, so adopting one doesn't lock you out of the other. The upgrade path framing matters: you can start by running current scripts under OSH, then move individual scripts to YSH as you rewrite them.

Why a new shell instead of just using bash

The project maintains a FAQ and a dedicated post, "Why Create a New Unix Shell?", along with a "Simplest Explanation" and a "Tour of YSH." These exist because the design decisions — strictness, structured data, a Python-like syntax — are deliberate departures from shell tradition, and the authors expect the "why not just fix bash" question. The blog archive spans 2016–2024, so the rationale has been documented over a long development period rather than asserted once.

What this means if you're deciding whether to try it

• If you have a pile of working bash scripts and want fewer silent bugs, OSH is the relevant entry point — it runs existing scripts, and the strictness features address the undefined-variable class of failure.
• If you write Python or JavaScript and have been avoiding shell, YSH is the relevant entry point, particularly if you need to move JSON or other structured data through pipelines.
• If you want to evaluate the reasoning before installing, the FAQ, the "Why Create a New Unix Shell?" post, and the YSH tour are the primary sources.

The project is developed in the oils-for-unix/oils repository on GitHub, with editor support via oils.vim. Build results are published across ci.oilshell.org, mb.oilshell.org, and op.oilshell.org, and user questions are directed to the #oil-help channel on Zulip.

Oils is a project that describes itself as "our upgrade path from bash to a better language and runtime." It ships two shells inside a single 2 MB binary called oils-for-unix: OSH, which runs your existing shell scripts, and YSH, aimed at Python and JavaScript users who want to avoid traditional shell syntax. The website at oils.pub is the project's home for installation instructions, documentation, a blog, and a language reference.

The two shells in one binary

Both live inside the same oils-for-unix binary, so installing one gives you access to both.

What the site offers

• Install — entry point for getting Oils onto your system.
• Docs — documentation for the project.
• Blog — posts dating 2016–2024, originally at oilshell.org, covering topics like the Oils 2023 FAQ, "Why Create a New Unix Shell?", a YSH tour, and "YSH vs. Shell Idioms."
• Oils Reference — language reference material.
• Latest Release / All Releases — release downloads and version history.
• Editor support — oils.vim for Vim users.
• Source — the oils-for-unix/oils repository on GitHub.

Where to get help and follow along

• Zulip chat at oilshell.zulipchat.com, with channels including #oil-help for user questions, #oil-discuss-public for general discussion, and #oil-dev for code changes (login required for that last one).
• Community — /r/oilsforunix on Reddit.
• Updates — follow @oilsforunix on Mastodon or Twitter, or subscribe via RSS.
• Contact — the maintainer's email is listed on the site (andy at oilshell dot org).
• Contributing — a # help-wanted section suggests places to start changing the code.

Who it's for

If you have working shell scripts and want a shell that runs them while catching errors like undefined variables, OSH is the relevant piece. If you come from Python or JavaScript and find traditional shell awkward, YSH is the intended audience. The project frames itself as an upgrade path rather than a replacement you adopt all at once.

The site does not list pricing information, so nothing here should be read as confirming whether the software or any related service is free or paid.

Oils (oils.pub) is the home of OSH and YSH, two shells that ship inside a single oils-for-unix binary. The site itself is mainly a landing page: it points you to the install page, the docs, the blog, and the community channels rather than hosting long-form content. If you are looking for reference material, release notes, or a place to ask questions, use the links below.

Documentation and reference

• Docs — linked from the top navigation on oils.pub. This is the entry point for written documentation.
• Oils Reference — the reference section for OSH and YSH. Use it when you need exact syntax or builtin behavior rather than a tutorial.
• Install — the install page, also in the top navigation. OSH and YSH live inside the same oils-for-unix binary, so one install gives you both.
• All Releases — the site links to /release/latest/ and an "All Releases" page for version history.

The homepage shows a short example of the difference between the two shells: OSH runs existing shell scripts and reports errors such as fatal: Undefined variable 'oops', while YSH is aimed at Python and JavaScript users who want to avoid shell quirks, with examples like json read < x.json.

Blog and release announcements

The blog lives at oilshell.org, not on oils.pub. The site describes it as covering 2016–2024 and lists posts including "Oils 2023 FAQ," "Why Create a New Unix Shell?," "The Simplest Explanation," "A Tour of YSH," and "YSH vs. Shell Idioms."

To get notified about new posts, the site offers:

• Mastodon: @oilsforunix
• Twitter: @oilsforunix
• RSS
• Reddit

Community and support

The site also links a #help-wanted section for places to start contributing, and notes that build results are published to ci.oilshell.org, mb.oilshell.org, or op.oilshell.org.

Editor support

For Vim users, the project points to oils.vim editor support, linked from the GitHub repo.

Quick answer

If you want to read: start with Docs and the Oils Reference on oils.pub, then the blog at oilshell.org. If you want to ask: use Zulip #oil-help. If you want to contribute: check #help-wanted and the GitHub repo. If you want to follow updates: RSS, Mastodon, or Twitter under @oilsforunix.

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.

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.