Install Gramex

You can try Gramex without installing using the Gramex IDE.

Try the Gramex IDE
(Log in with any Google account)

There are 3 ways to install the Gramex Community Edition.

1. Docker. Best to try out new versions, or to deploy apps.
2. Conda (RECOMMENDED). Best for beginners and Python developers
3. Pip. Best for people contributing to Gramex

Docker install

Install Docker. Then run:

docker run -it -p 9988:9988 gramener/gramex /bin/sh -l

In the container, run gramex --help to verify the Gramex version. Now you can Run your first app.

• -it runs Docker with an interactive terminal – so you can type commands in it (e.g. gramex)
• -p 9988:9988 maps host port 9988 (outside) to container port 9988 (inside)
• gramener/gramex:latest runs the latest Gramex instance (pulling it if required)
• /bin/sh -l logs into ash (a shell) that you can run commands in

If you have a Gramex app on your host at /proj, you can run it by adding -v /proj:/app, like this:

docker run -it -p 9988:9988 -v /proj:/app gramener/gramex

• -v /proj:/app maps the directory /proj on the host to the container’s /app (the working directory)
• gramex runs Gramex from the working directory

Note:

• Gramex is built on Alpine Linux
• The default working directory is /app
• The default user is gramex, without a password
• Use doas instead of sudo to run as root
• Use sh -l to run an interactive shell. If you don’t use -l, run source ~/.profile to add Python and gramex to your path

To upgrade Gramex, run:

docker pull gramener/gramex

To remove the Gramex docker image, run:

docker rmi gramener/gramex

Conda install

1. Install Anaconda3. (See archives for older versions).
2. Install node.js 12 or later from the node.js download page.

On the Anaconda prompt, run:

conda create -y --name gramex python=3.9            # Create a new environment
conda activate gramex                               # Activate it
pip install --upgrade gramex
gramex setup --all

This is what your screen might look like when installing:

Now you can Run your first app.

To upgrade Gramex, run:

pip install --upgrade gramex
gramex setup --all

To remove the Gramex environment, run:

conda env remove -n gramex

Pip install

1. Install Python 3.7+.
2. Install node.js 12 or above from the node.js download page.

To install or upgrade Gramex, run this on a terminal:

pip install --upgrade gramex
gramex setup --all

To install a specific Gramex release, run:

# Install a specific version of Gramex
pip install gramex==1.47.0

# Install a specific branch or tag from the Gramex source code
pip install https://github.com/gramener/gramex/archive/dev.zip
pip install https://github.com/gramener/gramex/archive/v1.47.0.zip

If you’re developing on Gramex, clone it and install a local version:

git clone https://github.com/gramener/gramex.git
pip install -e gramex

To remove the Gramex package, run:

pip uninstall gramex

Install Gramex Enterprise

Gramex Enterprise is offered under a commercial license and provides enterprise security features.

To install it, install Gramex first.

Then run:

pip install gramexenterprise    # Install Gramex Enterprise
gramex license accept           # Accept the Gramex license

Upgrade Gramex Enterprise

To upgrade Gramex Enterprise, run:

pip install --upgrade gramexenterprise

Uninstall Gramex Enterprise

To remove Gramex Enterprise, run:

pip uninstall gramexenterprise

Run a Gramex app

Open a terminal where you can run Gramex.

If you installed via Conda or Pip:

1. Open your Anaconda Prompt / Command Prompt / shell.
2. Run conda activate gramex to activate the Gramex environment

If you inslled via Docker:

1. Run docker run -it -p 9988:9988 gramener/gramex:latest /bin/bash

In this terminal, run gramex --help to verify that Gramex is installed properly. You should see this.

If you see an error, see the Troubleshooting section.

To start a Gramex project, create a new folder and run gramex init from that folder by typing this in your terminal.

mkdir project
cd project
gramex init

You should see an output like this:

Run gramex. This will start Gramex and show an output like this:

Open http://localhost:9988/ in your browser, and you should see the sample app.

Now you’re ready to move to the quickstart tutorial

Troubleshooting

If Gramex does not install:

• If you are behind a HTTP proxy, use pip install --proxy=http://{proxy-host}:{port} .... You can use conda with a proxy too.

If Gramex does not run:

• Gramex works only on Python 3.7 and above. Type python --version. If you don’t see “Python 3.7” (or higher), upgrade Python and re-install Gramex.
• Try uninstalling and re-installing Gramex. Stop Gramex and all other Python applications when re-installing.
• Make sure that typing gramex runs the Gramex executable, and is not aliased to a different command.
• If UI components are not working, install node.js, ensure that it’s on your PATH, and run gramex setup --all to set up all apps again.

VSCode Extension

Install Gramex Snippets extension for VSCode IDE for Gramex related code snippets.