This guide provides step-by-step instructions for installing DEgym and its dependencies for different use cases.
DEgym uses uv for fast and reliable package management. This is the recommended approach for all installations.
Follow the installation guide in the uv documentation to install uv on your system.
Quick installation:
# On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
Clone the DEgym repository:
git clone git@github.com:instadeepai/degym.git
cd degym
Choose the installation option that best fits your use case:
This installs the core DEgym framework with SciPy-based integrators, suitable for most chemical reactor simulations.
uv sync
What’s included:
For developers contributing to DEgym or those who need testing and linting tools.
uv sync --group test
uv pip install -e .
What’s included:
For advanced users who need Julia-based differential equation solvers.
uv sync --group diffeqpy
uv run build/install_julia.py
What’s included:
[!WARNING] The DiffEqPy installation requires Julia and is currently not stable for local or CI builds. Use with caution in production environments.
| Group | Purpose | Use Case |
|---|---|---|
| Core | Basic DEgym functionality | Building and running RL environments |
| test | Development tools | Contributing to DEgym, testing |
| diffeqpy | Advanced solvers | High-performance numerical integration |
For containerized deployments, DEgym provides several Docker images optimized for different use cases. The Dockerfile uses multi-stage builds for efficiency.
Build from the project root directory using the Dockerfile located in build/Dockerfile:
# Build the minimal production image
docker build -f build/Dockerfile --target degym-minimal -t degym-minimal .
# Build the CI/testing image
docker build -f build/Dockerfile --target degym-main -t degym-main .
# Build the DiffEqPy image (experimental)
docker build -f build/Dockerfile --target degym-diffeqpy -t degym-diffeqpy .
Best Practices:
Development vs Production:
# Run with the minimal image
docker run -it degym-minimal bash -c "python -c 'import degym; print(\"DEgym loaded successfully!\")'"
# Run with volume mounting for development
docker run -v $(pwd):/app/workspace -it degym-main bash -c "cd workspace && uv run pytest"
# Interactive development with the CI image
docker run -v $(pwd):/app/workspace -it degym-main bash
For development with Docker:
# Build the CI image
docker build -f build/Dockerfile --target degym-main -t degym-main .
# Run tests
docker run -v $(pwd):/app/workspace degym-main bash -c "cd workspace && uv run pytest"
# Run with interactive shell for debugging
docker run -v $(pwd):/app/workspace -it degym-main bash
Use uv run to execute commands within the virtual environment:
# Run Python scripts
uv run python path_to_script.py
# Run tests
uv run pytest
# Install additional packages
uv add package_name
If you encounter ModuleNotFoundError when running scripts, make sure you have installed the package in editable mode:
uv pip install -e .
Verify your installation by running a simple test:
# Run basic tests
uv run pytest tests/
# Test a simple environment
uv run python -c "import degym; print('DEgym imported successfully!')"
1. ModuleNotFoundError
# Solution: Update PYTHONPATH
export PYTHONPATH=$PWD:$PYTHONPATH
2. uv command not found
# Solution: Ensure uv is in your PATH or reinstall
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc # or restart terminal
3. Docker Build Issues
# Solution: Ensure you're building from the project root
docker build -f build/Dockerfile --target degym-main -t degym-main .
# Clear Docker cache if needed
docker builder prune
After successful installation:
degym_tutorials/ directory.[!TIP] For the best development experience, we recommend using the Development Installation with your preferred IDE configured for Python development.