Nitrogen is a simple mini-language used by
nitro run to set up and launch apps.
It's similar in principle to Dockerfiles, and enables you to author and share single-file plain-Python programs that can be easily set up and launched by others without having to read through a pile of installation instructions.
You can think of Nitrogen as a peer-to-peer software distribution tool that eliminates manual installs and updates.
Nitrogen instructions are placed inside a comment block, usually at the top of a file, enclosed between two
=== (triple-equals) comments:
The header has three parts:
- (Optional) YAML metadata.
- Nitrogen instructions.
Here's a minimal example without metadata. It simply prints "Hello World!":
Here's a more complete example, with metadata:
Lines starting with
# are ignored. The following example prints only "Bob"
Long lines can be broken into multiple lines using a
\ at the end of a line. The following examples are equivalent:
Instructions have the following form:
Arguments containing whitespace can be quoted, like this:
The instruction is not case-sensitive. but UPPERCASE is preferred for readability.
Instructions must begin with a
Setup:, and are run in order. If an error is encountered,
nitro run is aborted.
For instructions that accept file paths:
file-path must be relative and slash-separated for platform independence (
/path/to/file). The path is automatically translated to the correct format required by the target platform.
File operations outside the current working directory are not allowed.
ECHO prints its arguments.
FILE writes a text file at
file-path containing everything in between the two
file-path must be relative and slash-separated (
/path/to/file) for platform independence. The path is automatically translated to the correct format required by the target platform.
Write three lines to
GET fetches a file from a
https:// URL and saves it at
GET is useful for fetching any additional files related to the app, like datasets, configuration files, images, or even other source files.
file-path is not provided, the filename is deduced from the URL. If
file-path is a directory (ends with a
/), the filename is deduced from the URL and written to the directory.
Fetch a file and save it to
Fetch a file and save it to
license.txt and save it to
FROM sets a base URL for subsequent
The primary function of
FROM is to simplify repetitive
SHOW prints the contents of a file, similar to
cat on Unix or
type on Windows.
ENV sets the environment variable named
name to value
RUN executes a command. If an error is encountered or
-verbose is set, it prints
python -m pip install -r requirements.txt:
START is similar to
RUN, except that it streams
STDOUT to the terminal.
It is typically used for the final instruction in a file for launching long-running services like Flask, Tornado, Starlette, etc. where it's useful to inspect the command's output while running.
Use special variables to refer to the file containing Nitrogen instructions.
Given a file
| ||File path|| |
| ||File's parent directory|| |
| ||File name with extension|| |
| ||File name without extension|| |
| ||File extension|| |
Special variables are useful when you want to avoid hard-coding the current file name in instructions.
Example 1. Setting an environment variable for Flask:
Example 2. Launching an app using Uvicorn:
To test if the Nitrogen instructions in your app are working as expected, you can pass
-source (the source directory), like this:
app.py is located in the directory
nitro command will start a temporary local file server hosting the files in
path/to/app/sources at http://localhost:12345/ and execute
app.py from http://localhost:12345/app.py.