Environment variables
For advanced usage, troubleshooting, and built-in variables, see below. For general information about using environment variables in DipDup config files, see Config.
Envfiles
DipDup supports loading environment variables from a file or many. Use -e or --env-file option to specify the path to the file. The file should contain key-value pairs in the format KEY=VALUE, one per line. Comments can be added using #.
You can use multiple -e options to load variables from multiple files. The variables are loaded in the order they are specified, with later files overriding earlier ones.
dipdup -C compose -e local.env -e secrets.env run
To generate an env file from config, use the dipdup config env command. This command will create a file with all the environment variables used in your configuration, including their values.
# Generate an env file from the config
dipdup -C compose config env -o envfile.env
# Include internal variables
dipdup -C compose config env -i -o envfile.env
Run dipdup config env -h to see available parameters.
Built-in variables
Some variables with DIPDUP_ prefix allow users to modify parameters that affect the behavior of the whole framework. Choosing the right combination of flags for an indexer project can improve performance, reduce RAM consumption, or enable useful features.
DipDup uses multiple environment variables internally. They read once on process start and usually do not change during runtime. You can either set variables in active shell or create an env file and pass it with -e CLI option. See Config for general usage.
| name | description |
|---|---|
DIPDUP_CI | Running in GitHub Actions (detected if not set) |
DIPDUP_DEBUG | Enable debug logging and additional checks |
DIPDUP_DOCKER | Running in Docker (detected if not set) |
DIPDUP_JSON_LOG | Print logs in JSON format |
DIPDUP_LOW_MEMORY | Reduce the size of caches and buffers for low-memory environments (only for debugging!) |
DIPDUP_MIGRATIONS | Enable migrations with aerich |
DIPDUP_NEXT | Enable experimental and breaking features from the next major release |
DIPDUP_NO_LINTER | Don't format and lint generated files with ruff |
DIPDUP_NO_BASE | Don't recreate files from base project template |
DIPDUP_NO_SYMLINK | Don't create magic symlink in the package root even when used as cwd |
DIPDUP_NO_VERSION_CHECK | Disable warning about running unstable or out-of-date DipDup version |
DIPDUP_PACKAGE_PATH | Disable package discovery and use the specified path |
DIPDUP_REPLAY_PATH | Path to datasource replay files; used in tests (dev only) |
DIPDUP_TEST | Running in tests (disables Sentry and some checks) |
You can also access these values as dipdup.env module attributes.
dipdup.env file
dipdup.env fileYou can also create a dipdup.env file in the current working directory. This file will be loaded automatically when you run DipDup and take precedence over other sources. This is mostly useful for internal variables.
## Enable debug mode for every `dipdup` command from cwd
echo "DIPDUP_DEBUG=1" >> dipdup.env
Envfiles and git
Generally you should avoid commiting env-files to git repository because of possible leak of API keys and other secrets. However, sometimes it can be useful. Consider this safe and useful snippet:
# do not edit this file!
POSTGRES_HOST=localhost
HASURA_HOST=localhost
It allows you to run DipDup locally using DB and Hasura in Docker Compose:
dipdup -C compose -e local.env run
If you know what you are doing and want to include envfile with the project, add the following string to the end of .gitignore and .dockerignore:
!local.env
Troubleshooting
If DipDup apparently has "lost" your env variable, these steps may help:
- Open a new terminal, activate virtual environment with
source .venv/bin/activate, and try again. - Run
exportcommand (shell command, not DipDup one) to dump the current shell environment. If something here seems out of place, check the~/.bashrcor~/.zshrcdepending on your shell. - You can use the following command to dump all env variables used by framework:
dipdup config env --internal --unsafe.