uv_unix/
resource_limits.rs

1//! Helper for adjusting Unix resource limits.
2//!
3//! Linux has a historically low default limit of 1024 open file descriptors per process.
4//! macOS also defaults to a low soft limit (typically 256), though its hard limit is much
5//! higher. On modern multi-core machines, these low defaults can cause "too many open files"
6//! errors because uv infers concurrency limits from CPU count and may schedule more concurrent
7//! work than the default file descriptor limit allows.
8//!
9//! This module attempts to raise the soft limit to the hard limit at startup to avoid these
10//! errors without requiring users to manually configure their shell's `ulimit` settings.
11//! The raised limit is inherited by child processes, which is important for commands like
12//! `uv run` that spawn Python interpreters.
13//!
14//! See: <https://github.com/astral-sh/uv/issues/16999>
15
16use nix::errno::Errno;
17use nix::sys::resource::{Resource, getrlimit, rlim_t, setrlimit};
18use thiserror::Error;
19
20/// Errors that can occur when adjusting resource limits.
21#[derive(Debug, Error)]
22pub enum OpenFileLimitError {
23    #[error("failed to get open file limit: {}", .0.desc())]
24    GetLimitFailed(Errno),
25
26    #[error("encountered unexpected negative soft limit: {value}")]
27    NegativeSoftLimit { value: rlim_t },
28
29    #[error("soft limit ({current}) already meets the target ({target})")]
30    AlreadySufficient { current: u64, target: u64 },
31
32    #[error("failed to raise open file limit from {current} to {target}: {}", source.desc())]
33    SetLimitFailed {
34        current: u64,
35        target: u64,
36        source: Errno,
37    },
38}
39
40/// Maximum file descriptor limit to request.
41///
42/// We cap at 0x100000 (1,048,576) to match the typical Linux default (`/proc/sys/fs/nr_open`)
43/// and to avoid issues with extremely high limits.
44///
45/// `OpenJDK` uses this same cap because:
46///
47/// 1. Some code breaks if `RLIMIT_NOFILE` exceeds `i32::MAX` (despite the type being `u64`)
48/// 2. Code that iterates over all possible FDs, e.g., to close them, can timeout
49///
50/// See: <https://bugs.openjdk.org/browse/JDK-8324577>
51/// See: <https://github.com/oracle/graal/issues/11136>
52///
53/// Note: `rlim_t` is platform-specific (`u64` on Linux/macOS, `i64` on FreeBSD).
54const MAX_NOFILE_LIMIT: rlim_t = 0x0010_0000;
55
56/// Attempt to raise the open file descriptor limit to the maximum allowed.
57///
58/// This function tries to set the soft limit to `min(hard_limit, 0x100000)`. If the operation
59/// fails, it returns an error since the default limits may still be sufficient for the
60/// current workload.
61///
62/// Returns [`Ok`] with the new soft limit on successful adjustment, or an appropriate
63/// [`OpenFileLimitError`] if adjustment failed.
64///
65/// Note the type of `rlim_t` is platform-specific (`u64` on Linux/macOS, `i64` on FreeBSD), but
66/// this function always returns a [`u64`].
67pub fn adjust_open_file_limit() -> Result<u64, OpenFileLimitError> {
68    let (soft, hard) =
69        getrlimit(Resource::RLIMIT_NOFILE).map_err(OpenFileLimitError::GetLimitFailed)?;
70
71    // Convert `rlim_t` to `u64`. On FreeBSD, `rlim_t` is `i64` which may fail.
72    // On Linux and macOS, `rlim_t` is a `u64`, and the conversion is infallible.
73    let Some(soft) = rlim_t_to_u64(soft) else {
74        return Err(OpenFileLimitError::NegativeSoftLimit { value: soft });
75    };
76
77    // Cap the target limit to avoid issues with extremely high values.
78    // If hard is negative or exceeds MAX_NOFILE_LIMIT, use MAX_NOFILE_LIMIT.
79    #[expect(clippy::unnecessary_cast)]
80    let target = rlim_t_to_u64(hard.min(MAX_NOFILE_LIMIT)).unwrap_or(MAX_NOFILE_LIMIT as u64);
81
82    if soft >= target {
83        return Err(OpenFileLimitError::AlreadySufficient {
84            current: soft,
85            target,
86        });
87    }
88
89    // Try to raise the soft limit to the target.
90    // Safe because target <= MAX_NOFILE_LIMIT which fits in both i64 and u64.
91    let target_rlim = target as rlim_t;
92
93    setrlimit(Resource::RLIMIT_NOFILE, target_rlim, hard).map_err(|err| {
94        OpenFileLimitError::SetLimitFailed {
95            current: soft,
96            target,
97            source: err,
98        }
99    })?;
100
101    Ok(target)
102}
103
104/// Convert `rlim_t` to `u64`, returning `None` if negative.
105///
106/// On Linux/macOS, `rlim_t` is `u64` so this always succeeds.
107/// On FreeBSD, `rlim_t` is `i64` so negative values return `None`.
108#[expect(clippy::useless_conversion)]
109fn rlim_t_to_u64(value: rlim_t) -> Option<u64> {
110    u64::try_from(value).ok()
111}
uv_unix/resource_limits.rs

uv_unix/
resource_limits.rs
